@drzl/validation-core 3.18.0 → 3.20.0

package/dist/index.cjs

@@ -44,7 +44,9 @@ __export(index_exports, {
   NAME_MODES: () => NAME_MODES,
   NESTED_PREFIX: () => NESTED_PREFIX,
   applyTableCase: () => applyTableCase,
+  buildBrandPlan: () => buildBrandPlan,
   buildNestedPlan: () => buildNestedPlan,
+  columnMetaFacts: () => columnMetaFacts,
   describeSet: () => describeSet,
   formatCode: () => formatCode,
   importSpecifier: () => importSpecifier,
@@ -63,10 +65,12 @@ __export(index_exports, {
   pascalCase: () => pascalCase,
   renderDuplicateFinder: () => renderDuplicateFinder,
   resolveAffix: () => resolveAffix,
+  resolveBranding: () => resolveBranding,
   resolveConfiguredImport: () => resolveConfiguredImport,
   resolveNestedDepth: () => resolveNestedDepth,
   schemaName: () => schemaName,
   selectColumns: () => selectColumns,
+  tableMetaFacts: () => tableMetaFacts,
   typeName: () => typeName,
   updateColumns: () => updateColumns,
   validateAffix: () => validateAffix
@@ -78,6 +82,259 @@ var import_node_module = require("module");
 var import_node_path2 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
+// src/naming.ts
+var NAME_MODES = ["insert", "update", "select"];
+var DEFAULT_MODE_PREFIX = {
+  insert: "Insert",
+  update: "Update",
+  select: "Select"
+};
+var DEFAULT_TYPE_SUFFIX = {
+  insert: "Input",
+  update: "Input",
+  select: "Output"
+};
+var DEFAULT_SCHEMA_SUFFIX = "Schema";
+var AFFIX_PROBE_TABLE = "users";
+function spread(value, fallback) {
+  if (value === void 0) return { ...fallback };
+  if (typeof value === "string") return { insert: value, update: value, select: value };
+  return {
+    insert: value.insert ?? fallback.insert,
+    update: value.update ?? fallback.update,
+    select: value.select ?? fallback.select
+  };
+}
+function pascalCase(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[\s_-]+/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+function applyTableCase(tsName, tableCase) {
+  return tableCase === "pascal" ? pascalCase(tsName) : tsName;
+}
+function resolveAffix(opts) {
+  const affix = opts?.affix;
+  const legacy = opts?.schemaSuffix ?? DEFAULT_SCHEMA_SUFFIX;
+  const legacyMap = {
+    insert: legacy,
+    update: legacy,
+    select: legacy
+  };
+  return {
+    tableCase: affix?.tableCase ?? "preserve",
+    schema: {
+      prefix: spread(affix?.schema?.prefix, DEFAULT_MODE_PREFIX),
+      suffix: spread(affix?.schema?.suffix, legacyMap)
+    },
+    type: {
+      prefix: spread(affix?.type?.prefix, DEFAULT_MODE_PREFIX),
+      suffix: spread(affix?.type?.suffix, DEFAULT_TYPE_SUFFIX)
+    }
+  };
+}
+function schemaName(mode, tsName, affix) {
+  return affix.schema.prefix[mode] + applyTableCase(tsName, affix.tableCase) + affix.schema.suffix[mode];
+}
+function typeName(mode, tsName, affix) {
+  return affix.type.prefix[mode] + applyTableCase(tsName, affix.tableCase) + affix.type.suffix[mode];
+}
+var PREFIX_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var SUFFIX_RE = /^[A-Za-z0-9_$]+$/;
+function validateAffix(affix, schemaSuffix) {
+  const issues = [];
+  if (!affix) return issues;
+  const checkOne = (value, path2, kind) => {
+    if (value === "") return;
+    const ok = kind === "prefix" ? PREFIX_RE.test(value) : SUFFIX_RE.test(value);
+    if (ok) return;
+    issues.push({
+      path: path2,
+      message: `${JSON.stringify(value)} cannot appear in a TypeScript identifier. Use only letters, digits, "_" and "$"` + (kind === "prefix" ? ", and do not start with a digit." : ".")
+    });
+  };
+  const checkValue = (value, base, kind) => {
+    if (value === void 0) return;
+    if (typeof value === "string") {
+      checkOne(value, base, kind);
+      return;
+    }
+    for (const mode of NAME_MODES) {
+      const v = value[mode];
+      if (v !== void 0) checkOne(v, [...base, mode], kind);
+    }
+  };
+  checkValue(affix.schema?.prefix, ["schema", "prefix"], "prefix");
+  checkValue(affix.schema?.suffix, ["schema", "suffix"], "suffix");
+  checkValue(affix.type?.prefix, ["type", "prefix"], "prefix");
+  checkValue(affix.type?.suffix, ["type", "suffix"], "suffix");
+  if (issues.length) return issues;
+  const resolved = resolveAffix({ affix, schemaSuffix });
+  const collisions = (space, build) => {
+    const seen = /* @__PURE__ */ new Map();
+    for (const mode of NAME_MODES) {
+      const name = build(mode);
+      const first = seen.get(name);
+      if (first) {
+        issues.push({
+          path: [space],
+          message: `The ${space} names for "${first}" and "${mode}" collide: both resolve to "${name}". All three are emitted into the same file, so at least one prefix or suffix has to differ.`
+        });
+      } else {
+        seen.set(name, mode);
+      }
+    }
+  };
+  collisions("schema", (mode) => schemaName(mode, AFFIX_PROBE_TABLE, resolved));
+  collisions("type", (mode) => typeName(mode, AFFIX_PROBE_TABLE, resolved));
+  return issues;
+}
+
+// src/branding.ts
+function resolveBranding(opt) {
+  if (!opt) return void 0;
+  if (opt === true) return { foreignKeys: true, aliases: true };
+  if (opt.enabled === false) return void 0;
+  return { foreignKeys: opt.foreignKeys !== false, aliases: opt.aliases !== false };
+}
+var at = (tsName, column) => `${tsName}\0${column}`;
+function referenceOf(table, columnName) {
+  const col = table.columns.find((c) => c.name === columnName);
+  if (col?.references) return { sqlTable: col.references.table, column: col.references.column };
+  for (const fk of table.foreignKeys ?? []) {
+    const i = fk.columns.indexOf(columnName);
+    if (i === -1) continue;
+    const target = fk.foreignColumns[i];
+    if (target === void 0) continue;
+    return { sqlTable: fk.foreignTable, column: target };
+  }
+  return void 0;
+}
+function isKeyColumn(table, columnName) {
+  return (table.primaryKey?.columns ?? []).includes(columnName);
+}
+function buildBrandPlan(tables, opt) {
+  const resolved = resolveBranding(opt);
+  if (!resolved) return void 0;
+  const notes = [];
+  const byTs = /* @__PURE__ */ new Map();
+  const dupTs = /* @__PURE__ */ new Set();
+  for (const t of tables) {
+    if (byTs.has(t.tsName)) dupTs.add(t.tsName);
+    byTs.set(t.tsName, t);
+  }
+  for (const name of dupTs) {
+    byTs.delete(name);
+    notes.push(
+      `two tables are exported as "${name}", so nothing on either is branded: a brand token is built from the export name and the two would be indistinguishable.`
+    );
+  }
+  const bySqlName = /* @__PURE__ */ new Map();
+  for (const t of byTs.values()) {
+    const list = bySqlName.get(t.name) ?? [];
+    list.push(t);
+    bySqlName.set(t.name, list);
+  }
+  const tokens = /* @__PURE__ */ new Map();
+  const cache = /* @__PURE__ */ new Map();
+  const resolveToken = (tsName, columnName) => {
+    const start = at(tsName, columnName);
+    if (cache.has(start)) return cache.get(start);
+    const origin = byTs.get(tsName)?.columns.find((c) => c.name === columnName);
+    if (!origin || origin.arrayDimensions) {
+      cache.set(start, void 0);
+      return void 0;
+    }
+    const seen = /* @__PURE__ */ new Set();
+    let curTable = tsName;
+    let curColumn = columnName;
+    let answer;
+    let terminal;
+    for (; ; ) {
+      const key = at(curTable, curColumn);
+      if (seen.has(key)) {
+        notes.push(
+          `${tsName}.${columnName} references a cycle of foreign keys, so it is not branded.`
+        );
+        break;
+      }
+      seen.add(key);
+      const table = byTs.get(curTable);
+      const col = table?.columns.find((c) => c.name === curColumn);
+      if (!table || !col) break;
+      const ref = resolved.foreignKeys ? referenceOf(table, curColumn) : void 0;
+      if (ref) {
+        const candidates = bySqlName.get(ref.sqlTable) ?? [];
+        if (candidates.length !== 1) {
+          notes.push(
+            candidates.length === 0 ? `${tsName}.${columnName} references a table "${ref.sqlTable}" that is not in this analysis, so it is not branded.` : `${tsName}.${columnName} references "${ref.sqlTable}", which names more than one table here, so it is not branded.`
+          );
+          break;
+        }
+        const next = candidates[0];
+        if (!next.columns.some((c) => c.name === ref.column)) {
+          notes.push(
+            `${tsName}.${columnName} references ${next.tsName}.${ref.column}, which is not a column of that table, so it is not branded.`
+          );
+          break;
+        }
+        curTable = next.tsName;
+        curColumn = ref.column;
+        continue;
+      }
+      if (isKeyColumn(table, curColumn)) {
+        answer = `${curTable}.${curColumn}`;
+        terminal = col;
+      }
+      break;
+    }
+    if (answer && terminal && terminal.tsType !== origin.tsType) {
+      notes.push(
+        `${tsName}.${columnName} is a ${origin.tsType} and ${answer} is a ${terminal.tsType}, so it is not branded.`
+      );
+      answer = void 0;
+    }
+    cache.set(start, answer);
+    return answer;
+  };
+  for (const t of byTs.values()) {
+    for (const c of t.columns) {
+      const token = resolveToken(t.tsName, c.name);
+      if (token) tokens.set(at(t.tsName, c.name), token);
+    }
+  }
+  const aliases = /* @__PURE__ */ new Map();
+  if (resolved.aliases) {
+    const claimed = /* @__PURE__ */ new Map();
+    const draft = [];
+    for (const t of byTs.values()) {
+      for (const c of t.columns) {
+        const token = tokens.get(at(t.tsName, c.name));
+        if (token !== `${t.tsName}.${c.name}`) continue;
+        const alias = pascalCase(t.tsName) + pascalCase(c.name);
+        draft.push({ tsName: t.tsName, entry: { alias, column: c.name, token } });
+        claimed.set(alias, [...claimed.get(alias) ?? [], `${t.tsName}.${c.name}`]);
+      }
+    }
+    for (const { tsName, entry } of draft) {
+      const owners = claimed.get(entry.alias) ?? [];
+      if (owners.length > 1) continue;
+      aliases.set(tsName, [...aliases.get(tsName) ?? [], entry]);
+    }
+    for (const [alias, owners] of claimed) {
+      if (owners.length > 1) {
+        notes.push(
+          `${owners.join(" and ")} both name their brand alias "${alias}", so neither is exported. The schemas are unaffected; refer to the type as the select type's property instead.`
+        );
+      }
+    }
+  }
+  return {
+    brandOf: (tsName, columnName) => tokens.get(at(tsName, columnName)),
+    aliasesFor: (tsName) => aliases.get(tsName) ?? [],
+    any: tokens.size > 0,
+    notes
+  };
+}
+
 // src/checks.ts
 var COMPARISON = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(>=|<=|<>|!=|>|<|=)\s*(.+?)\s*$/;
 var IN_LIST = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s+IN\s*\((.+)\)\s*$/i;
@@ -351,113 +608,120 @@ function withTsExtension(p) {
   return `${p}.ts`;
 }
 
-// src/naming.ts
-var NAME_MODES = ["insert", "update", "select"];
-var DEFAULT_MODE_PREFIX = {
-  insert: "Insert",
-  update: "Update",
-  select: "Select"
-};
-var DEFAULT_TYPE_SUFFIX = {
-  insert: "Input",
-  update: "Input",
-  select: "Output"
-};
-var DEFAULT_SCHEMA_SUFFIX = "Schema";
-var AFFIX_PROBE_TABLE = "users";
-function spread(value, fallback) {
-  if (value === void 0) return { ...fallback };
-  if (typeof value === "string") return { insert: value, update: value, select: value };
-  return {
-    insert: value.insert ?? fallback.insert,
-    update: value.update ?? fallback.update,
-    select: value.select ?? fallback.select
-  };
+// src/meta.ts
+function labelled(name, text) {
+  return name ? `${name}: ${text}` : text;
 }
-function pascalCase(s) {
-  return s.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[\s_-]+/).filter(Boolean).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+function literalText(value, kind) {
+  return kind === "string" ? `'${value}'` : value;
 }
-function applyTableCase(tsName, tableCase) {
-  return tableCase === "pascal" ? pascalCase(tsName) : tsName;
+function columnCheckText(k) {
+  return labelled(k.name, `${k.column} ${k.operator} ${literalText(k.value, k.kind)}`);
 }
-function resolveAffix(opts) {
-  const affix = opts?.affix;
-  const legacy = opts?.schemaSuffix ?? DEFAULT_SCHEMA_SUFFIX;
-  const legacyMap = {
-    insert: legacy,
-    update: legacy,
-    select: legacy
-  };
-  return {
-    tableCase: affix?.tableCase ?? "preserve",
-    schema: {
-      prefix: spread(affix?.schema?.prefix, DEFAULT_MODE_PREFIX),
-      suffix: spread(affix?.schema?.suffix, legacyMap)
-    },
-    type: {
-      prefix: spread(affix?.type?.prefix, DEFAULT_MODE_PREFIX),
-      suffix: spread(affix?.type?.suffix, DEFAULT_TYPE_SUFFIX)
-    }
-  };
+function setText(k) {
+  return labelled(
+    k.name,
+    `${k.column} IN (${k.values.map((v) => literalText(v, k.kind)).join(", ")})`
+  );
 }
-function schemaName(mode, tsName, affix) {
-  return affix.schema.prefix[mode] + applyTableCase(tsName, affix.tableCase) + affix.schema.suffix[mode];
+function lengthText(k) {
+  return labelled(k.name, `length(${k.column}) ${k.operator} ${k.value}`);
 }
-function typeName(mode, tsName, affix) {
-  return affix.type.prefix[mode] + applyTableCase(tsName, affix.tableCase) + affix.type.suffix[mode];
+function cardinalityText(k) {
+  return labelled(k.name, `cardinality(${k.column}) ${k.operator} ${k.value}`);
 }
-var PREFIX_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-var SUFFIX_RE = /^[A-Za-z0-9_$]+$/;
-function validateAffix(affix, schemaSuffix) {
-  const issues = [];
-  if (!affix) return issues;
-  const checkOne = (value, path2, kind) => {
-    if (value === "") return;
-    const ok = kind === "prefix" ? PREFIX_RE.test(value) : SUFFIX_RE.test(value);
-    if (ok) return;
-    issues.push({
-      path: path2,
-      message: `${JSON.stringify(value)} cannot appear in a TypeScript identifier. Use only letters, digits, "_" and "$"` + (kind === "prefix" ? ", and do not start with a digit." : ".")
-    });
-  };
-  const checkValue = (value, base, kind) => {
-    if (value === void 0) return;
-    if (typeof value === "string") {
-      checkOne(value, base, kind);
+function rowText(k) {
+  return labelled(k.name, `${k.left} ${k.operator} ${k.right}`);
+}
+function takesScalarChecks(c) {
+  return !c.arrayDimensions && !c.shape;
+}
+function classifyChecks(table) {
+  const perColumn = /* @__PURE__ */ new Map();
+  const rows = [];
+  const unenforced = [];
+  const byName = new Map(table.columns.map((c) => [c.name, c]));
+  const add = (column, text, guard) => {
+    const c = byName.get(column);
+    if (!c || !guard(c)) {
+      unenforced.push(text);
       return;
     }
-    for (const mode of NAME_MODES) {
-      const v = value[mode];
-      if (v !== void 0) checkOne(v, [...base, mode], kind);
-    }
+    const list = perColumn.get(column) ?? [];
+    list.push(text);
+    perColumn.set(column, list);
   };
-  checkValue(affix.schema?.prefix, ["schema", "prefix"], "prefix");
-  checkValue(affix.schema?.suffix, ["schema", "suffix"], "suffix");
-  checkValue(affix.type?.prefix, ["type", "prefix"], "prefix");
-  checkValue(affix.type?.suffix, ["type", "suffix"], "suffix");
-  if (issues.length) return issues;
-  const resolved = resolveAffix({ affix, schemaSuffix });
-  const collisions = (space, build) => {
-    const seen = /* @__PURE__ */ new Map();
-    for (const mode of NAME_MODES) {
-      const name = build(mode);
-      const first = seen.get(name);
-      if (first) {
-        issues.push({
-          path: [space],
-          message: `The ${space} names for "${first}" and "${mode}" collide: both resolve to "${name}". All three are emitted into the same file, so at least one prefix or suffix has to differ.`
-        });
-      } else {
-        seen.set(name, mode);
-      }
+  for (const k of table.checks ?? []) {
+    const parsed = parseCheck(k.expression, k.name);
+    if (!parsed.ok) {
+      unenforced.push(labelled(k.name, (k.expression ?? "").trim()));
+      continue;
+    }
+    for (const c of parsed.checks) add(c.column, columnCheckText(c), takesScalarChecks);
+    for (const s of parsed.sets ?? []) add(s.column, setText(s), takesScalarChecks);
+    for (const l of parsed.lengths ?? []) add(l.column, lengthText(l), takesScalarChecks);
+    for (const a of parsed.cardinalities ?? [])
+      add(a.column, cardinalityText(a), (c) => !!c.arrayDimensions);
+    for (const r of parsed.rows ?? []) {
+      if (byName.has(r.left) && byName.has(r.right)) rows.push(rowText(r));
+      else unenforced.push(rowText(r));
     }
+  }
+  return { perColumn, rows, unenforced };
+}
+function columnDescription(facts) {
+  const parts = [];
+  if (facts.maxLength !== void 0) parts.push(`at most ${facts.maxLength} characters`);
+  if (facts.maxBytes !== void 0) parts.push(`at most ${facts.maxBytes} bytes`);
+  for (const c of facts.checks ?? []) parts.push(`CHECK ${c}`);
+  return parts.length ? parts.join(". ") : void 0;
+}
+function tableDescription(facts) {
+  const parts = [];
+  for (const c of facts.checks ?? []) parts.push(`CHECK ${c}`);
+  if (facts.unenforcedChecks?.length) {
+    parts.push(
+      `not enforced by this schema, the database also checks: ${facts.unenforcedChecks.join("; ")}`
+    );
+  }
+  return parts.length ? parts.join(". ") : void 0;
+}
+function columnMetaFacts(column, table, opts = {}) {
+  const checks = classifyChecks(table).perColumn.get(column.name);
+  const facts = {
+    ...column.sqlType ? { sqlType: column.sqlType } : {},
+    ...column.maxLength !== void 0 ? { maxLength: column.maxLength } : {},
+    ...column.maxBytes !== void 0 ? { maxBytes: column.maxBytes } : {},
+    ...column.hasDefault ? { hasDefault: true } : {},
+    ...column.isGenerated ? { generated: true } : {},
+    ...checks?.length ? { checks } : {}
   };
-  collisions("schema", (mode) => schemaName(mode, AFFIX_PROBE_TABLE, resolved));
-  collisions("type", (mode) => typeName(mode, AFFIX_PROBE_TABLE, resolved));
-  return issues;
+  if (!opts.description) return facts;
+  const description = columnDescription(facts);
+  return description ? { ...facts, description } : facts;
+}
+function tableMetaFacts(table, opts) {
+  const { rows, unenforced } = classifyChecks(table);
+  const pk = table.primaryKey?.columns ?? [];
+  const unique = (table.unique ?? []).map((k) => k.columns).filter((c) => c.length > 0);
+  const facts = {
+    table: table.name,
+    ...table.schema ? { schema: table.schema } : {},
+    ...opts.dialect ? { dialect: opts.dialect } : {},
+    mode: opts.mode,
+    ...pk.length ? { primaryKey: pk } : {},
+    ...unique.length ? { unique } : {},
+    ...table.readOnly ? { readOnly: true } : {},
+    ...rows.length ? { checks: rows } : {},
+    ...unenforced.length ? { unenforcedChecks: unenforced } : {}
+  };
+  if (!opts.description) return facts;
+  const description = tableDescription(facts);
+  return description ? { ...facts, description } : facts;
 }
 
 // src/nested.ts
+var import_analyzer = require("@drzl/analyzer");
 var NESTED_PREFIX = "Nested";
 function nestedSchemaName(mode, tsName, affix) {
   return NESTED_PREFIX + schemaName(mode, tsName, affix);
@@ -485,13 +749,14 @@ var KINDS_BY_MODE = {
 };
 var KIND_ORDER = { many: 0, manyToMany: 1, one: 2 };
 function omittedColumnsFor(parent, child) {
-  const back = (child.foreignKeys ?? []).filter((fk) => fk.foreignTable === parent.name);
+  const parentName = (0, import_analyzer.qualifiedTableName)(parent);
+  const back = (child.foreignKeys ?? []).filter((fk) => (0, import_analyzer.qualifiedForeignTable)(fk) === parentName);
   if (back.length === 1) return { omitted: [...back[0].columns] };
   if (back.length === 0) return { omitted: [] };
   const named = back.map((fk) => fk.columns.join("+")).join(", ");
   return {
     omitted: [],
-    note: `${child.tsName} has ${back.length} foreign keys to ${parent.name} (${named}), so which one this relation uses is not stated. None were omitted: supply them yourself.`
+    note: `${child.tsName} has ${back.length} foreign keys to ${parentName} (${named}), so which one this relation uses is not stated. None were omitted: supply them yourself.`
   };
 }
 function buildNestedPlan(root, tables, relations, mode, depth) {
@@ -500,14 +765,15 @@ function buildNestedPlan(root, tables, relations, mode, depth) {
 }
 function buildNode(table, omitted, tables, relations, mode, depth) {
   if (depth <= 0) return { table, omitted, arms: [] };
-  const byDbName = new Map(tables.map((t) => [t.name, t]));
+  const byName = new Map(tables.map((t) => [(0, import_analyzer.qualifiedTableName)(t), t]));
   const allowed = KINDS_BY_MODE[mode];
   const columnNames = new Set(table.columns.map((c) => c.name));
   const taken = /* @__PURE__ */ new Set();
   const arms = [];
-  const candidates = relations.filter((r) => r.from === table.name && allowed.has(r.kind)).sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]);
+  const self = (0, import_analyzer.qualifiedTableName)(table);
+  const candidates = relations.filter((r) => r.from === self && allowed.has(r.kind)).sort((a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind]);
   for (const rel of candidates) {
-    const child = byDbName.get(rel.to);
+    const child = byName.get(rel.to);
     if (!child) continue;
     const key = child.tsName;
     if (columnNames.has(key)) continue;
@@ -733,7 +999,9 @@ async function formatCode(code, filePath, fmt) {
   NAME_MODES,
   NESTED_PREFIX,
   applyTableCase,
+  buildBrandPlan,
   buildNestedPlan,
+  columnMetaFacts,
   describeSet,
   formatCode,
   importSpecifier,
@@ -752,10 +1020,12 @@ async function formatCode(code, filePath, fmt) {
   pascalCase,
   renderDuplicateFinder,
   resolveAffix,
+  resolveBranding,
   resolveConfiguredImport,
   resolveNestedDepth,
   schemaName,
   selectColumns,
+  tableMetaFacts,
   typeName,
   updateColumns,
   validateAffix