@drzl/analyzer 1.17.7 → 1.20.0

package/dist/index.cjs

@@ -36,10 +36,18 @@ __export(index_exports, {
   isDrizzleView: () => isDrizzleView,
   isReadOnlyRelation: () => isReadOnlyRelation,
   isRelationsV2: () => isRelationsV2,
+  qualifiedForeignTable: () => qualifiedForeignTable,
+  qualifiedTableName: () => qualifiedTableName,
   readRelationsV2: () => readRelationsV2
 });
 module.exports = __toCommonJS(index_exports);
 var import_meta = {};
+function qualifiedTableName(table) {
+  return table.schema ? `${table.schema}.${table.name}` : table.name;
+}
+function qualifiedForeignTable(fk) {
+  return fk.foreignSchema ? `${fk.foreignSchema}.${fk.foreignTable}` : fk.foreignTable;
+}
 function renderSqlLiteral(v) {
   if (v === null || v === void 0) return "NULL";
   if (typeof v === "number" || typeof v === "bigint") return String(v);
@@ -385,27 +393,43 @@ function isRelationsV2(val) {
     )
   );
 }
+function qualifiedNameOfDrizzleTable(tbl) {
+  const name = getSymbolOf(tbl, "drizzle:Name");
+  if (typeof name !== "string" || !name) return void 0;
+  const schema = getSymbolOf(tbl, "drizzle:Schema");
+  return typeof schema === "string" && schema ? `${schema}.${name}` : name;
+}
 function readRelationsV2(val, issues = []) {
   const out = [];
   for (const [tableKey, entry] of Object.entries(val)) {
-    const from = getSymbolOf(entry.table, "drizzle:Name") ?? entry.name ?? tableKey;
+    const from = qualifiedNameOfDrizzleTable(entry.table) ?? entry.name ?? tableKey;
     for (const [fieldName, r] of Object.entries(entry.relations ?? {})) {
-      const to = r?.targetTableName;
+      const to = qualifiedNameOfDrizzleTable(r?.targetTable) ?? r?.targetTableName;
       if (typeof to !== "string" || !to) {
         issues.push({
           code: "DRZL_ANL_REL_V2",
           level: "warn",
-          message: `Relation "${fieldName}" on "${from}" names no target table and was skipped.`
+          message: `Relation "${fieldName}" on "${from}" names no target table and was skipped.`,
+          path: from
         });
         continue;
       }
-      const via = getSymbolOf(r.throughTable, "drizzle:Name") ?? getSymbolOf(r.through?.sourceTable, "drizzle:Name") ?? void 0;
+      const via = qualifiedNameOfDrizzleTable(r.throughTable) ?? qualifiedNameOfDrizzleTable(r.through?.sourceTable) ?? void 0;
       if (via) out.push({ kind: "manyToMany", from, to, via });
       else out.push({ kind: r.relationType === "many" ? "many" : "one", from, to });
     }
   }
   return out;
 }
+function unknownColumnHint(reason) {
+  if (reason === "custom") {
+    return "A customType has no runtime shape to read. Declare it with .$type<T>() and turn on typedColumns to give the validator the type.";
+  }
+  if (reason === "gel-temporal") {
+    return "A Gel temporal column holds an instance of a class from the `gel` package, which DRZL cannot import, so it is left untyped on purpose rather than guessed at. Turn on typedColumns to recover the declared type, and validate the value yourself.";
+  }
+  return "Open an issue naming the column type so it can be modelled, or declare it with .$type<T>() and turn on typedColumns.";
+}
 var _SchemaAnalyzer = class _SchemaAnalyzer {
   constructor(schemaPath) {
     this.schemaPath = schemaPath;
@@ -456,6 +480,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         code: "DRZL_ANL_EXTRACONFIG",
         level: "warn",
         message: `Could not evaluate the extra-config callback for table "${tableName}": ${e.message}`,
+        path: tableName,
         hint: "Indexes, composite keys, checks and table-level foreign keys will be missing for this table."
       });
       return [];
@@ -509,9 +534,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
     };
     const foreignColumnsObj = this.getSymbol(ref.foreignTable, "drizzle:Columns") ?? {};
     const toForeignTs = this.dbToTsNames(foreignColumnsObj);
+    const foreignSchema = this.getSymbol(ref.foreignTable, "drizzle:Schema");
     return {
       columns: (ref.columns ?? []).map((c) => toTs(c?.name)),
       foreignTable: this.getSymbol(ref.foreignTable, "drizzle:Name") ?? "unknown",
+      ...foreignSchema ? { foreignSchema } : {},
       foreignColumns: (ref.foreignColumns ?? []).map((c) => toForeignTs(c?.name)),
       onDelete: action(fk?.onDelete, fk?._onDelete),
       onUpdate: action(fk?.onUpdate, fk?._onUpdate),
@@ -560,7 +587,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
    * on each returned value, so the stand-in results must carry that method or the call throws.
    */
   readRelationsObject(val, exportName, issues) {
-    const from = this.getSymbol(val.table, "drizzle:Name") ?? exportName;
+    const from = qualifiedNameOfDrizzleTable(val.table) ?? exportName;
     const make = (kind) => (table, cfg) => ({
       kind,
       referencedTable: table,
@@ -574,7 +601,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       const built = val.config({ one: make("one"), many: make("many") });
       const out = [];
       for (const rel of Object.values(built ?? {})) {
-        const to = this.getSymbol(rel?.referencedTable, "drizzle:Name");
+        const to = qualifiedNameOfDrizzleTable(rel?.referencedTable);
         if (to) out.push({ kind: rel.kind, from, to });
       }
       return out;
@@ -583,6 +610,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         code: "DRZL_ANL_RELATIONS",
         level: "warn",
         message: `Could not read the relations declared in "${exportName}": ${e.message}`,
+        path: from,
         hint: "Relations for this table will be missing from the analysis."
       });
       return [];
@@ -603,10 +631,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       if (fks.length < 2) continue;
       const fkCols = new Set(fks.flatMap((f) => f.columns));
       if (!t.columns.every((c) => fkCols.has(c.name))) continue;
-      const targets = [...new Set(fks.map((f) => f.foreignTable))];
+      const targets = [...new Set(fks.map(qualifiedForeignTable))];
       if (targets.length !== 2) continue;
-      out.push({ kind: "manyToMany", from: targets[0], to: targets[1], via: t.name });
-      out.push({ kind: "manyToMany", from: targets[1], to: targets[0], via: t.name });
+      const via = qualifiedTableName(t);
+      out.push({ kind: "manyToMany", from: targets[0], to: targets[1], via });
+      out.push({ kind: "manyToMany", from: targets[1], to: targets[0], via });
     }
     return out;
   }
@@ -928,7 +957,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           if (/Bool/i.test(ctor)) return { tsType: "boolean", dbType: "BOOLEAN" };
           if (/TimestampTz/i.test(ctor)) return { tsType: "Date", dbType: "TIMESTAMPTZ" };
           if (/Timestamp|LocalDateString|LocalTime|DateDuration|RelDuration|Duration/i.test(ctor))
-            return { tsType: "unknown", dbType: "UNKNOWN" };
+            return { tsType: "unknown", dbType: "UNKNOWN", unnameable: "gel-temporal" };
         }
         return { tsType: "unknown", dbType: "UNKNOWN" };
     }
@@ -944,7 +973,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
     const uniqueGroups = /* @__PURE__ */ new Map();
     for (const [colName, outerCol] of Object.entries(columnsObj)) {
       const { element: col, dimensions: arrayDims } = unwrapArrayColumn(outerCol);
-      let { tsType, dbType } = this.mapColumnType(col);
+      const mapped = this.mapColumnType(col);
+      let { tsType, dbType } = mapped;
       if (tsType === "unknown" && /At$/.test(colName)) {
         tsType = "Date";
         dbType = "INTEGER";
@@ -987,13 +1017,26 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           code: "DRZL_ANL_UNKNOWN_COLUMN",
           level: "warn",
           message: `Column "${colName}" on table "${tsName}" has no known type${sqlType2 ? ` (SQL type ${sqlType2})` : ""}, so its validator will accept any value.`,
-          hint: shape === "custom" ? "A customType has no runtime shape to read. Declare it with .$type<T>() and turn on typedColumns to give the validator the type." : "Open an issue naming the column type so it can be modelled, or declare it with .$type<T>() and turn on typedColumns."
+          path: `${tsName}.${colName}`,
+          hint: unknownColumnHint(shape === "custom" ? "custom" : mapped.unnameable)
         });
       }
+      const dims = arrayDims || v1?.arrayDimensions || 0;
+      const declaredSqlType = (() => {
+        let raw;
+        try {
+          raw = typeof outerCol?.getSQLType === "function" ? outerCol.getSQLType() : void 0;
+        } catch {
+          return void 0;
+        }
+        if (typeof raw !== "string" || !raw) return void 0;
+        return raw.endsWith("]") ? raw : raw + "[]".repeat(dims);
+      })();
       columns.push({
         name: colName,
         tsType,
         dbType,
+        ...declaredSqlType ? { sqlType: declaredSqlType } : {},
         nullable,
         hasDefault,
         isGenerated,
@@ -1070,6 +1113,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       if (!col) continue;
       col.references = {
         table: fk.foreignTable,
+        ...fk.foreignSchema ? { schema: fk.foreignSchema } : {},
         column: fk.foreignColumns[0],
         onDelete: fk.onDelete,
         onUpdate: fk.onUpdate
@@ -1142,9 +1186,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
             }
           }
           if (opts.includeRelations) {
+            const self = qualifiedTableName(table);
             for (const fk of table.foreignKeys ?? []) {
-              relations.push({ kind: "one", from: table.name, to: fk.foreignTable });
-              relations.push({ kind: "many", from: fk.foreignTable, to: table.name });
+              const target = qualifiedForeignTable(fk);
+              relations.push({ kind: "one", from: self, to: target });
+              relations.push({ kind: "many", from: target, to: self });
             }
           }
         } else if (this.isRelationsObject(val)) {
@@ -1172,7 +1218,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         issues.push({
           code: "DRZL_ANL_TABLE",
           level: "warn",
-          message: `Failed to analyze export ${name}: ${String(e)}`
+          message: `Failed to analyze export ${name}: ${String(e)}`,
+          path: name
         });
       }
     }
@@ -1217,11 +1264,21 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       relations.push(...this.inferManyToMany(tables));
     }
     if (opts.includeRelations && opts.includeHeuristicRelations) {
-      const tableNames = new Set(tables.map((t) => t.name));
-      const findTarget = (base) => {
-        if (tableNames.has(base)) return base;
-        if (tableNames.has(base + "s")) return base + "s";
-        if (tableNames.has(base + "es")) return base + "es";
+      const byBareName = /* @__PURE__ */ new Map();
+      for (const t of tables) {
+        const list = byBareName.get(t.name);
+        if (list) list.push(t);
+        else byBareName.set(t.name, [t]);
+      }
+      const findTarget = (base, from) => {
+        for (const candidate of [base, base + "s", base + "es"]) {
+          const hits = byBareName.get(candidate);
+          if (!hits?.length) continue;
+          const sameSchema = hits.filter((t) => t.schema === from.schema);
+          if (sameSchema.length === 1) return qualifiedTableName(sameSchema[0]);
+          if (hits.length === 1) return qualifiedTableName(hits[0]);
+          return void 0;
+        }
         return void 0;
       };
       for (const t of tables) {
@@ -1229,8 +1286,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           if (c.references) continue;
           if (c.name.endsWith("Id")) {
             const base = c.name.slice(0, -2);
-            const target = findTarget(base);
-            if (target) relations.push({ kind: "one", from: t.name, to: target });
+            const target = findTarget(base, t);
+            if (target) relations.push({ kind: "one", from: qualifiedTableName(t), to: target });
           }
         }
       }
@@ -1401,5 +1458,7 @@ var index_default = SchemaAnalyzer;
   isDrizzleView,
   isReadOnlyRelation,
   isRelationsV2,
+  qualifiedForeignTable,
+  qualifiedTableName,
   readRelationsV2
 });

package/dist/index.d.cts

@@ -8,28 +8,91 @@ interface Issue {
     level: 'info' | 'warn' | 'error';
     message: string;
     hint?: string;
+    /**
+     * Where the issue is, as `table` or `table.column`.
+     *
+     * Declared since this interface existed and set by nothing, so every consumer wanting to group
+     * warnings by table had to read the names back out of the English in `message`. `drzl doctor` is
+     * the first such consumer and a report built by regex over prose breaks the first time a message
+     * is reworded, so the names are stated here instead.
+     *
+     * Still optional: an issue about the schema as a whole, such as an unidentifiable dialect, is
+     * about no table and says so by omitting this.
+     */
     path?: string;
 }
+/**
+ * Why a column has no type, where "nobody has modelled it" is not the answer.
+ *
+ * The distinction exists because it changes the advice. A column class this file has no arm for is
+ * a gap someone can close, and the warning tells its author to say so. A Gel temporal column is
+ * not: the value is an instance of a class from the `gel` package, DRZL cannot import that package,
+ * and no generator could emit a check for it even knowing the name. Leaving it `unknown` is the
+ * measured answer rather than an omission, and its warning should say that instead of asking for a
+ * bug report that is already closed.
+ */
+type UnnameableReason = 'gel-temporal';
 interface ColumnRef {
     table: string;
     column: string;
 }
+/**
+ * A link between two tables, each end named by `qualifiedTableName`.
+ *
+ * Qualified rather than bare, because a bare database name identifies a table only while no two
+ * SQL schemas hold it: `to: 'users'` cannot say whether it means `public.users` or
+ * `reporting.users`, and every consumer resolves these strings back to a table object. A table in
+ * the default schema has no prefix, so nothing about a single-schema analysis changes.
+ */
 interface Relation {
     kind: 'one' | 'many' | 'manyToMany';
+    /** Qualified table name: `users`, or `reporting.users`. */
     from: string;
+    /** Qualified table name: `users`, or `reporting.users`. */
     to: string;
+    /** Qualified name of the join table, for m2m. */
     via?: string;
 }
 interface Column {
     name: string;
     tsType: string;
+    /**
+     * A coarse label for the column's kind, not its type.
+     *
+     * `varchar`, `char` and `text` are all `TEXT` here, deliberately: exactly one consumer reads
+     * this, `isIntegerColumn`, and it only asks whether a number is whole. Use `sqlType` for the
+     * question this name suggests it answers.
+     */
     dbType: string;
+    /**
+     * The column's type as the database declares it, from Drizzle's own `getSQLType()`:
+     * `varchar(255)`, `numeric(10, 2)`, `timestamp with time zone`, `text[]`, or an enum's type
+     * name.
+     *
+     * The one fact about a column that no validator schema can carry, and the one every other fact
+     * here is a consequence of. A generator that emits metadata beside its schemas has nothing else
+     * to put in it: `dbType` is a label rather than a type, and the declared width lives in
+     * `maxLength`, the precision in `min`/`max`, and neither of those says which type produced it.
+     *
+     * The two Drizzle majors disagree about an array and are reconciled here, measured rather than
+     * assumed: 0.4x wraps the column in a `PgArray` whose own answer is already `text[]`, while v1
+     * leaves the class alone and raises `dimensions`, so its answer is the bare `text`. The suffix
+     * is added from `arrayDimensions` when the type does not already carry one, so a consumer
+     * cannot tell which major produced its metadata.
+     *
+     * Absent where the builder has no `getSQLType` or it throws. Nothing is guessed from the class
+     * name: an invented type string reads exactly like a real one, and there is no way for a
+     * consumer to tell them apart.
+     */
+    sqlType?: string;
     nullable: boolean;
     hasDefault: boolean;
     isGenerated: boolean;
     defaultExpression?: string;
     references?: {
         table: string;
+        /** SQL schema of the referenced table, absent for the default one. See `ForeignKey`. */
+        schema?: string;
         column: string;
         onDelete?: string;
         onUpdate?: string;
@@ -272,6 +335,17 @@ interface ForeignKey {
     name?: string;
     columns: string[];
     foreignTable: string;
+    /**
+     * The SQL schema the referenced table lives in, absent for the default one, exactly as
+     * `Table.schema` is.
+     *
+     * `foreignTable` is a bare database name and Postgres lets two schemas hold the same one, so a
+     * key pointing at `reporting.users` recorded the identical string a key pointing at
+     * `public.users` records. Every consumer that resolves a key back to a table object did so by
+     * that string, and therefore resolved to whichever of the two it saw first. Use
+     * `qualifiedForeignTable` rather than reading the two fields apart.
+     */
+    foreignSchema?: string;
     foreignColumns: string[];
     onDelete?: string;
     onUpdate?: string;
@@ -279,6 +353,15 @@ interface ForeignKey {
 interface Table {
     name: string;
     tsName: string;
+    /**
+     * The SQL schema the table was declared in, from `pgSchema('reporting').table(...)` and the
+     * MySQL and SingleStore equivalents. Absent for a table declared with plain `pgTable`, which is
+     * the only spelling of the default schema there is: Drizzle refuses `pgSchema('public')`
+     * outright, with "Postgres is using public schema by default".
+     *
+     * `name` stays bare, so two tables in two schemas share one. `qualifiedTableName` is what tells
+     * them apart, and is what every name-addressed surface in DRZL matches against.
+     */
     schema?: string;
     columns: Column[];
     primaryKey?: Key;
@@ -298,6 +381,28 @@ interface Enum {
     name: string;
     values: string[];
 }
+/**
+ * The one name that identifies a table across every SQL schema in an analysis.
+ *
+ * `reporting.users` where the table names a schema, and the bare `users` where it does not. The
+ * bare form for the default schema is deliberate and is what makes this safe to reach for
+ * everywhere: on a schema module that never calls `pgSchema`, and that is nearly all of them, this
+ * returns exactly `table.name`, so every file name, every export, every config pattern and every
+ * emitted path is byte for byte what it was.
+ *
+ * `public.users` is not produced here. Drizzle refuses `pgSchema('public')`, so no analysis can
+ * ever carry `schema: 'public'`, and a table with no schema *is* the public one. `public.` exists
+ * only as a spelling a config may use, resolved by `@drzl/cli`.
+ */
+declare function qualifiedTableName(table: {
+    name: string;
+    schema?: string;
+}): string;
+/** The same name, for the far end of a foreign key. */
+declare function qualifiedForeignTable(fk: {
+    foreignTable: string;
+    foreignSchema?: string;
+}): string;
 interface Analysis {
     drizzleVersion?: string;
     dialect: Dialect;
@@ -532,4 +637,4 @@ declare class SchemaAnalyzer {
     analyze(opts?: AnalyzeOptions): Promise<Analysis>;
 }
 
-export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, readRelationsV2 };
+export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, type UnnameableReason, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, qualifiedForeignTable, qualifiedTableName, readRelationsV2 };

package/dist/index.d.ts

@@ -8,28 +8,91 @@ interface Issue {
     level: 'info' | 'warn' | 'error';
     message: string;
     hint?: string;
+    /**
+     * Where the issue is, as `table` or `table.column`.
+     *
+     * Declared since this interface existed and set by nothing, so every consumer wanting to group
+     * warnings by table had to read the names back out of the English in `message`. `drzl doctor` is
+     * the first such consumer and a report built by regex over prose breaks the first time a message
+     * is reworded, so the names are stated here instead.
+     *
+     * Still optional: an issue about the schema as a whole, such as an unidentifiable dialect, is
+     * about no table and says so by omitting this.
+     */
     path?: string;
 }
+/**
+ * Why a column has no type, where "nobody has modelled it" is not the answer.
+ *
+ * The distinction exists because it changes the advice. A column class this file has no arm for is
+ * a gap someone can close, and the warning tells its author to say so. A Gel temporal column is
+ * not: the value is an instance of a class from the `gel` package, DRZL cannot import that package,
+ * and no generator could emit a check for it even knowing the name. Leaving it `unknown` is the
+ * measured answer rather than an omission, and its warning should say that instead of asking for a
+ * bug report that is already closed.
+ */
+type UnnameableReason = 'gel-temporal';
 interface ColumnRef {
     table: string;
     column: string;
 }
+/**
+ * A link between two tables, each end named by `qualifiedTableName`.
+ *
+ * Qualified rather than bare, because a bare database name identifies a table only while no two
+ * SQL schemas hold it: `to: 'users'` cannot say whether it means `public.users` or
+ * `reporting.users`, and every consumer resolves these strings back to a table object. A table in
+ * the default schema has no prefix, so nothing about a single-schema analysis changes.
+ */
 interface Relation {
     kind: 'one' | 'many' | 'manyToMany';
+    /** Qualified table name: `users`, or `reporting.users`. */
     from: string;
+    /** Qualified table name: `users`, or `reporting.users`. */
     to: string;
+    /** Qualified name of the join table, for m2m. */
     via?: string;
 }
 interface Column {
     name: string;
     tsType: string;
+    /**
+     * A coarse label for the column's kind, not its type.
+     *
+     * `varchar`, `char` and `text` are all `TEXT` here, deliberately: exactly one consumer reads
+     * this, `isIntegerColumn`, and it only asks whether a number is whole. Use `sqlType` for the
+     * question this name suggests it answers.
+     */
     dbType: string;
+    /**
+     * The column's type as the database declares it, from Drizzle's own `getSQLType()`:
+     * `varchar(255)`, `numeric(10, 2)`, `timestamp with time zone`, `text[]`, or an enum's type
+     * name.
+     *
+     * The one fact about a column that no validator schema can carry, and the one every other fact
+     * here is a consequence of. A generator that emits metadata beside its schemas has nothing else
+     * to put in it: `dbType` is a label rather than a type, and the declared width lives in
+     * `maxLength`, the precision in `min`/`max`, and neither of those says which type produced it.
+     *
+     * The two Drizzle majors disagree about an array and are reconciled here, measured rather than
+     * assumed: 0.4x wraps the column in a `PgArray` whose own answer is already `text[]`, while v1
+     * leaves the class alone and raises `dimensions`, so its answer is the bare `text`. The suffix
+     * is added from `arrayDimensions` when the type does not already carry one, so a consumer
+     * cannot tell which major produced its metadata.
+     *
+     * Absent where the builder has no `getSQLType` or it throws. Nothing is guessed from the class
+     * name: an invented type string reads exactly like a real one, and there is no way for a
+     * consumer to tell them apart.
+     */
+    sqlType?: string;
     nullable: boolean;
     hasDefault: boolean;
     isGenerated: boolean;
     defaultExpression?: string;
     references?: {
         table: string;
+        /** SQL schema of the referenced table, absent for the default one. See `ForeignKey`. */
+        schema?: string;
         column: string;
         onDelete?: string;
         onUpdate?: string;
@@ -272,6 +335,17 @@ interface ForeignKey {
     name?: string;
     columns: string[];
     foreignTable: string;
+    /**
+     * The SQL schema the referenced table lives in, absent for the default one, exactly as
+     * `Table.schema` is.
+     *
+     * `foreignTable` is a bare database name and Postgres lets two schemas hold the same one, so a
+     * key pointing at `reporting.users` recorded the identical string a key pointing at
+     * `public.users` records. Every consumer that resolves a key back to a table object did so by
+     * that string, and therefore resolved to whichever of the two it saw first. Use
+     * `qualifiedForeignTable` rather than reading the two fields apart.
+     */
+    foreignSchema?: string;
     foreignColumns: string[];
     onDelete?: string;
     onUpdate?: string;
@@ -279,6 +353,15 @@ interface ForeignKey {
 interface Table {
     name: string;
     tsName: string;
+    /**
+     * The SQL schema the table was declared in, from `pgSchema('reporting').table(...)` and the
+     * MySQL and SingleStore equivalents. Absent for a table declared with plain `pgTable`, which is
+     * the only spelling of the default schema there is: Drizzle refuses `pgSchema('public')`
+     * outright, with "Postgres is using public schema by default".
+     *
+     * `name` stays bare, so two tables in two schemas share one. `qualifiedTableName` is what tells
+     * them apart, and is what every name-addressed surface in DRZL matches against.
+     */
     schema?: string;
     columns: Column[];
     primaryKey?: Key;
@@ -298,6 +381,28 @@ interface Enum {
     name: string;
     values: string[];
 }
+/**
+ * The one name that identifies a table across every SQL schema in an analysis.
+ *
+ * `reporting.users` where the table names a schema, and the bare `users` where it does not. The
+ * bare form for the default schema is deliberate and is what makes this safe to reach for
+ * everywhere: on a schema module that never calls `pgSchema`, and that is nearly all of them, this
+ * returns exactly `table.name`, so every file name, every export, every config pattern and every
+ * emitted path is byte for byte what it was.
+ *
+ * `public.users` is not produced here. Drizzle refuses `pgSchema('public')`, so no analysis can
+ * ever carry `schema: 'public'`, and a table with no schema *is* the public one. `public.` exists
+ * only as a spelling a config may use, resolved by `@drzl/cli`.
+ */
+declare function qualifiedTableName(table: {
+    name: string;
+    schema?: string;
+}): string;
+/** The same name, for the far end of a foreign key. */
+declare function qualifiedForeignTable(fk: {
+    foreignTable: string;
+    foreignSchema?: string;
+}): string;
 interface Analysis {
     drizzleVersion?: string;
     dialect: Dialect;
@@ -532,4 +637,4 @@ declare class SchemaAnalyzer {
     analyze(opts?: AnalyzeOptions): Promise<Analysis>;
 }
 
-export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, readRelationsV2 };
+export { type Analysis, type AnalyzeOptions, type Check, type Column, type ColumnRef, type ColumnShape, type Dialect, type Enum, type ForeignKey, type Index, type Issue, type Key, type Relation, SchemaAnalyzer, type Table, type UnnameableReason, SchemaAnalyzer as default, describeV1Column, isDrizzleView, isReadOnlyRelation, isRelationsV2, qualifiedForeignTable, qualifiedTableName, readRelationsV2 };

package/dist/index.js

@@ -1,4 +1,10 @@
 // src/index.ts
+function qualifiedTableName(table) {
+  return table.schema ? `${table.schema}.${table.name}` : table.name;
+}
+function qualifiedForeignTable(fk) {
+  return fk.foreignSchema ? `${fk.foreignSchema}.${fk.foreignTable}` : fk.foreignTable;
+}
 function renderSqlLiteral(v) {
   if (v === null || v === void 0) return "NULL";
   if (typeof v === "number" || typeof v === "bigint") return String(v);
@@ -344,27 +350,43 @@ function isRelationsV2(val) {
     )
   );
 }
+function qualifiedNameOfDrizzleTable(tbl) {
+  const name = getSymbolOf(tbl, "drizzle:Name");
+  if (typeof name !== "string" || !name) return void 0;
+  const schema = getSymbolOf(tbl, "drizzle:Schema");
+  return typeof schema === "string" && schema ? `${schema}.${name}` : name;
+}
 function readRelationsV2(val, issues = []) {
   const out = [];
   for (const [tableKey, entry] of Object.entries(val)) {
-    const from = getSymbolOf(entry.table, "drizzle:Name") ?? entry.name ?? tableKey;
+    const from = qualifiedNameOfDrizzleTable(entry.table) ?? entry.name ?? tableKey;
     for (const [fieldName, r] of Object.entries(entry.relations ?? {})) {
-      const to = r?.targetTableName;
+      const to = qualifiedNameOfDrizzleTable(r?.targetTable) ?? r?.targetTableName;
       if (typeof to !== "string" || !to) {
         issues.push({
           code: "DRZL_ANL_REL_V2",
           level: "warn",
-          message: `Relation "${fieldName}" on "${from}" names no target table and was skipped.`
+          message: `Relation "${fieldName}" on "${from}" names no target table and was skipped.`,
+          path: from
         });
         continue;
       }
-      const via = getSymbolOf(r.throughTable, "drizzle:Name") ?? getSymbolOf(r.through?.sourceTable, "drizzle:Name") ?? void 0;
+      const via = qualifiedNameOfDrizzleTable(r.throughTable) ?? qualifiedNameOfDrizzleTable(r.through?.sourceTable) ?? void 0;
       if (via) out.push({ kind: "manyToMany", from, to, via });
       else out.push({ kind: r.relationType === "many" ? "many" : "one", from, to });
     }
   }
   return out;
 }
+function unknownColumnHint(reason) {
+  if (reason === "custom") {
+    return "A customType has no runtime shape to read. Declare it with .$type<T>() and turn on typedColumns to give the validator the type.";
+  }
+  if (reason === "gel-temporal") {
+    return "A Gel temporal column holds an instance of a class from the `gel` package, which DRZL cannot import, so it is left untyped on purpose rather than guessed at. Turn on typedColumns to recover the declared type, and validate the value yourself.";
+  }
+  return "Open an issue naming the column type so it can be modelled, or declare it with .$type<T>() and turn on typedColumns.";
+}
 var _SchemaAnalyzer = class _SchemaAnalyzer {
   constructor(schemaPath) {
     this.schemaPath = schemaPath;
@@ -415,6 +437,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         code: "DRZL_ANL_EXTRACONFIG",
         level: "warn",
         message: `Could not evaluate the extra-config callback for table "${tableName}": ${e.message}`,
+        path: tableName,
         hint: "Indexes, composite keys, checks and table-level foreign keys will be missing for this table."
       });
       return [];
@@ -468,9 +491,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
     };
     const foreignColumnsObj = this.getSymbol(ref.foreignTable, "drizzle:Columns") ?? {};
     const toForeignTs = this.dbToTsNames(foreignColumnsObj);
+    const foreignSchema = this.getSymbol(ref.foreignTable, "drizzle:Schema");
     return {
       columns: (ref.columns ?? []).map((c) => toTs(c?.name)),
       foreignTable: this.getSymbol(ref.foreignTable, "drizzle:Name") ?? "unknown",
+      ...foreignSchema ? { foreignSchema } : {},
       foreignColumns: (ref.foreignColumns ?? []).map((c) => toForeignTs(c?.name)),
       onDelete: action(fk?.onDelete, fk?._onDelete),
       onUpdate: action(fk?.onUpdate, fk?._onUpdate),
@@ -519,7 +544,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
    * on each returned value, so the stand-in results must carry that method or the call throws.
    */
   readRelationsObject(val, exportName, issues) {
-    const from = this.getSymbol(val.table, "drizzle:Name") ?? exportName;
+    const from = qualifiedNameOfDrizzleTable(val.table) ?? exportName;
     const make = (kind) => (table, cfg) => ({
       kind,
       referencedTable: table,
@@ -533,7 +558,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       const built = val.config({ one: make("one"), many: make("many") });
       const out = [];
       for (const rel of Object.values(built ?? {})) {
-        const to = this.getSymbol(rel?.referencedTable, "drizzle:Name");
+        const to = qualifiedNameOfDrizzleTable(rel?.referencedTable);
         if (to) out.push({ kind: rel.kind, from, to });
       }
       return out;
@@ -542,6 +567,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         code: "DRZL_ANL_RELATIONS",
         level: "warn",
         message: `Could not read the relations declared in "${exportName}": ${e.message}`,
+        path: from,
         hint: "Relations for this table will be missing from the analysis."
       });
       return [];
@@ -562,10 +588,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       if (fks.length < 2) continue;
       const fkCols = new Set(fks.flatMap((f) => f.columns));
       if (!t.columns.every((c) => fkCols.has(c.name))) continue;
-      const targets = [...new Set(fks.map((f) => f.foreignTable))];
+      const targets = [...new Set(fks.map(qualifiedForeignTable))];
       if (targets.length !== 2) continue;
-      out.push({ kind: "manyToMany", from: targets[0], to: targets[1], via: t.name });
-      out.push({ kind: "manyToMany", from: targets[1], to: targets[0], via: t.name });
+      const via = qualifiedTableName(t);
+      out.push({ kind: "manyToMany", from: targets[0], to: targets[1], via });
+      out.push({ kind: "manyToMany", from: targets[1], to: targets[0], via });
     }
     return out;
   }
@@ -887,7 +914,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           if (/Bool/i.test(ctor)) return { tsType: "boolean", dbType: "BOOLEAN" };
           if (/TimestampTz/i.test(ctor)) return { tsType: "Date", dbType: "TIMESTAMPTZ" };
           if (/Timestamp|LocalDateString|LocalTime|DateDuration|RelDuration|Duration/i.test(ctor))
-            return { tsType: "unknown", dbType: "UNKNOWN" };
+            return { tsType: "unknown", dbType: "UNKNOWN", unnameable: "gel-temporal" };
         }
         return { tsType: "unknown", dbType: "UNKNOWN" };
     }
@@ -903,7 +930,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
     const uniqueGroups = /* @__PURE__ */ new Map();
     for (const [colName, outerCol] of Object.entries(columnsObj)) {
       const { element: col, dimensions: arrayDims } = unwrapArrayColumn(outerCol);
-      let { tsType, dbType } = this.mapColumnType(col);
+      const mapped = this.mapColumnType(col);
+      let { tsType, dbType } = mapped;
       if (tsType === "unknown" && /At$/.test(colName)) {
         tsType = "Date";
         dbType = "INTEGER";
@@ -946,13 +974,26 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           code: "DRZL_ANL_UNKNOWN_COLUMN",
           level: "warn",
           message: `Column "${colName}" on table "${tsName}" has no known type${sqlType2 ? ` (SQL type ${sqlType2})` : ""}, so its validator will accept any value.`,
-          hint: shape === "custom" ? "A customType has no runtime shape to read. Declare it with .$type<T>() and turn on typedColumns to give the validator the type." : "Open an issue naming the column type so it can be modelled, or declare it with .$type<T>() and turn on typedColumns."
+          path: `${tsName}.${colName}`,
+          hint: unknownColumnHint(shape === "custom" ? "custom" : mapped.unnameable)
         });
       }
+      const dims = arrayDims || v1?.arrayDimensions || 0;
+      const declaredSqlType = (() => {
+        let raw;
+        try {
+          raw = typeof outerCol?.getSQLType === "function" ? outerCol.getSQLType() : void 0;
+        } catch {
+          return void 0;
+        }
+        if (typeof raw !== "string" || !raw) return void 0;
+        return raw.endsWith("]") ? raw : raw + "[]".repeat(dims);
+      })();
       columns.push({
         name: colName,
         tsType,
         dbType,
+        ...declaredSqlType ? { sqlType: declaredSqlType } : {},
         nullable,
         hasDefault,
         isGenerated,
@@ -1029,6 +1070,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       if (!col) continue;
       col.references = {
         table: fk.foreignTable,
+        ...fk.foreignSchema ? { schema: fk.foreignSchema } : {},
         column: fk.foreignColumns[0],
         onDelete: fk.onDelete,
         onUpdate: fk.onUpdate
@@ -1101,9 +1143,11 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
             }
           }
           if (opts.includeRelations) {
+            const self = qualifiedTableName(table);
             for (const fk of table.foreignKeys ?? []) {
-              relations.push({ kind: "one", from: table.name, to: fk.foreignTable });
-              relations.push({ kind: "many", from: fk.foreignTable, to: table.name });
+              const target = qualifiedForeignTable(fk);
+              relations.push({ kind: "one", from: self, to: target });
+              relations.push({ kind: "many", from: target, to: self });
             }
           }
         } else if (this.isRelationsObject(val)) {
@@ -1131,7 +1175,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         issues.push({
           code: "DRZL_ANL_TABLE",
           level: "warn",
-          message: `Failed to analyze export ${name}: ${String(e)}`
+          message: `Failed to analyze export ${name}: ${String(e)}`,
+          path: name
         });
       }
     }
@@ -1176,11 +1221,21 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       relations.push(...this.inferManyToMany(tables));
     }
     if (opts.includeRelations && opts.includeHeuristicRelations) {
-      const tableNames = new Set(tables.map((t) => t.name));
-      const findTarget = (base) => {
-        if (tableNames.has(base)) return base;
-        if (tableNames.has(base + "s")) return base + "s";
-        if (tableNames.has(base + "es")) return base + "es";
+      const byBareName = /* @__PURE__ */ new Map();
+      for (const t of tables) {
+        const list = byBareName.get(t.name);
+        if (list) list.push(t);
+        else byBareName.set(t.name, [t]);
+      }
+      const findTarget = (base, from) => {
+        for (const candidate of [base, base + "s", base + "es"]) {
+          const hits = byBareName.get(candidate);
+          if (!hits?.length) continue;
+          const sameSchema = hits.filter((t) => t.schema === from.schema);
+          if (sameSchema.length === 1) return qualifiedTableName(sameSchema[0]);
+          if (hits.length === 1) return qualifiedTableName(hits[0]);
+          return void 0;
+        }
         return void 0;
       };
       for (const t of tables) {
@@ -1188,8 +1243,8 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
           if (c.references) continue;
           if (c.name.endsWith("Id")) {
             const base = c.name.slice(0, -2);
-            const target = findTarget(base);
-            if (target) relations.push({ kind: "one", from: t.name, to: target });
+            const target = findTarget(base, t);
+            if (target) relations.push({ kind: "one", from: qualifiedTableName(t), to: target });
           }
         }
       }
@@ -1360,5 +1415,7 @@ export {
   isDrizzleView,
   isReadOnlyRelation,
   isRelationsV2,
+  qualifiedForeignTable,
+  qualifiedTableName,
   readRelationsV2
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drzl/analyzer",
-  "version": "1.17.7",
+  "version": "1.20.0",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",