@stacksjs/database 0.70.88 → 0.70.90

package/dist/drivers/sqlite.js

@@ -0,0 +1,397 @@
+import { log } from "@stacksjs/logging";
+function italic(str) {
+  return `\x1B[3m${str}\x1B[23m`;
+}
+import { app } from "@stacksjs/config";
+import { db, SQLITE_BOOTSTRAP_PRAGMAS } from "../utils";
+import { ok } from "@stacksjs/error-handling";
+import { fetchOtherModelRelations, getModelName, getPivotTables, getTableName } from "@stacksjs/orm";
+import { path } from "@stacksjs/path";
+import { fs, globSync } from "@stacksjs/storage";
+import { snakeCase } from "@stacksjs/strings";
+import {
+  arrangeColumns,
+  checkPivotMigration,
+  deleteFrameworkModels,
+  deleteMigrationFiles,
+  fetchTables,
+  findDifferingKeys,
+  getLastMigrationFields,
+  getLikeableForeignKey,
+  getUpvoteTableName,
+  isArrayEqual,
+  mapFieldTypeToColumnType,
+  pluckChanges
+} from "./helpers";
+import { dropCommonTables } from "./defaults/traits";
+export async function resetSqliteDatabase() {
+  await deleteFrameworkModels();
+  await deleteMigrationFiles();
+  await dropSqliteTables();
+  return ok("All tables dropped successfully!");
+}
+export async function configureSqlitePragmas() {
+  try {
+    for (const pragma of SQLITE_BOOTSTRAP_PRAGMAS)
+      await db.unsafe(pragma).execute();
+  } catch (err) {
+    log.debug(`[sqlite] Failed to apply pragmas: ${err.message}`);
+  }
+}
+export async function dropSqliteTables() {
+  const userModelFiles = globSync([path.userModelsPath("*.ts"), path.storagePath("framework/defaults/app/Models/**/*.ts")], { absolute: !0 }), tables = await fetchTables(), safeName = /^[a-z_][\w]*$/i;
+  await db.unsafe("PRAGMA foreign_keys = OFF").execute();
+  try {
+    for (const table of tables) {
+      if (!safeName.test(table))
+        throw Error(`[sqlite] Refusing to drop table with unsafe name: ${table}`);
+      await db.unsafe(`DROP TABLE IF EXISTS "${table}"`).execute();
+    }
+    await db.unsafe('DROP TABLE IF EXISTS "migrations"').execute();
+    await dropCommonTables();
+    for (const userModel of userModelFiles) {
+      const userModelPath = (await import(userModel)).default, pivotTables = await getPivotTables(userModelPath, userModel);
+      for (const pivotTable of pivotTables) {
+        if (!safeName.test(pivotTable.table))
+          throw Error(`[sqlite] Refusing to drop pivot table with unsafe name: ${pivotTable.table}`);
+        await db.unsafe(`DROP TABLE IF EXISTS "${pivotTable.table}"`).execute();
+      }
+    }
+  } finally {
+    await db.unsafe("PRAGMA foreign_keys = ON").execute();
+  }
+}
+export function fetchSqliteFile() {
+  if (app.env === "testing")
+    return fetchTestSqliteFile();
+  return path.userDatabasePath("stacks.sqlite");
+}
+export function fetchTestSqliteFile() {
+  return path.userDatabasePath("stacks_testing.sqlite");
+}
+export async function generateSqliteMigration(modelPath) {
+  const model = (await import(modelPath)).default, fileName = path.basename(modelPath), tableName = await getTableName(model, modelPath), fieldsString = JSON.stringify(model.attributes, null, 2), copiedModelPath = path.frameworkPath(`cache/models/${fileName}`);
+  let haveFieldsChanged = !1;
+  if (fs.existsSync(copiedModelPath)) {
+    log.debug(`Fields have already been generated for ${tableName}`);
+    const previousFields = await getLastMigrationFields(fileName);
+    if (JSON.stringify(previousFields, null, 2) === fieldsString) {
+      log.debug(`Fields have not changed for ${tableName}`);
+      return;
+    }
+    haveFieldsChanged = !0;
+    log.debug(`Fields have changed for ${tableName}`);
+  } else
+    log.debug(`Fields have not been generated for ${tableName}`);
+  await Bun.$`mkdir -p ${path.frameworkPath("cache/models")} && cp ${modelPath} ${copiedModelPath}`;
+  const hasBeenMigrated = !1;
+  log.debug(`Has ${tableName} been migrated? ${hasBeenMigrated}`);
+  if (haveFieldsChanged)
+    await createAlterTableMigration(modelPath);
+  else
+    await createTableMigration(modelPath);
+}
+export async function copyModelFiles(modelPath) {
+  const model = (await import(modelPath)).default, fileName = path.basename(modelPath), tableName = await getTableName(model, modelPath), fieldsString = JSON.stringify(model.attributes, null, 2), copiedModelPath = path.frameworkPath(`cache/models/${fileName}`);
+  if (fs.existsSync(copiedModelPath)) {
+    log.debug(`Fields have already been generated for ${tableName}`);
+    const previousFields = await getLastMigrationFields(fileName);
+    if (JSON.stringify(previousFields, null, 2) === fieldsString) {
+      log.debug(`Fields have not changed for ${tableName}`);
+      return;
+    }
+  }
+  await Bun.$`mkdir -p ${path.frameworkPath("cache/models")} && cp ${modelPath} ${copiedModelPath}`;
+}
+async function createTableMigration(modelPath) {
+  log.debug("createTableMigration modelPath:", modelPath);
+  const model = (await import(modelPath)).default, tableName = getTableName(model, modelPath), modelName = getModelName(model, modelPath), twoFactorEnabled = model.traits?.useAuth && typeof model.traits.useAuth !== "boolean" ? model.traits.useAuth.useTwoFactor : !1;
+  await createPivotTableMigration(model, modelPath);
+  const otherModelRelations = await fetchOtherModelRelations(modelName), useTimestamps = model?.traits?.useTimestamps ?? model?.traits?.timestampable ?? !0, useSocials = model?.traits?.useSocials && Array.isArray(model.traits.useSocials) && model.traits.useSocials.length > 0, useLikeable = Array.isArray(model?.traits?.likeable) ? model.traits.likeable.length > 0 : Boolean(model?.traits?.likeable), useSoftDeletes = model?.traits?.useSoftDeletes ?? model?.traits?.softDeletable ?? !1, usePasskey = (typeof model.traits?.useAuth === "object" && model.traits.useAuth.usePasskey) ?? !1, useBillable = model.traits?.billable || !1, useUuid = model.traits?.useUuid || !1;
+  let migrationContent = `import type { Database } from '@stacksjs/database'
+`;
+  migrationContent += `import { sql } from '@stacksjs/database'
+
+`;
+  migrationContent += `export async function up(db: Database<any>) {
+`;
+  migrationContent += `  await (db as any).schema
+`;
+  migrationContent += `    .createTable('${tableName}')
+`;
+  migrationContent += `    .addColumn('id', 'integer', col => col.primaryKey().autoIncrement())
+`;
+  if (useUuid)
+    migrationContent += `    .addColumn('uuid', 'text')
+`;
+  if (useSocials) {
+    const socials = model.traits?.useSocials || [];
+    if (socials.includes("google"))
+      migrationContent += `    .addColumn('google_id', 'text')
+`;
+    if (socials.includes("github"))
+      migrationContent += `    .addColumn('github_id', 'text')
+`;
+    if (socials.includes("apple"))
+      migrationContent += `    .addColumn('apple_id', 'text')
+`;
+    if (socials.includes("twitter"))
+      migrationContent += `    .addColumn('twitter_id', 'text')
+`;
+    if (socials.includes("facebook"))
+      migrationContent += `    .addColumn('facebook_id', 'text')
+`;
+  }
+  for (const [fieldName, options] of arrangeColumns(model.attributes)) {
+    const fieldOptions = options, fieldNameFormatted = snakeCase(fieldName), columnType = mapFieldTypeToColumnType(fieldOptions.validation?.rule, "sqlite");
+    migrationContent += `    .addColumn('${fieldNameFormatted}', ${columnType}`;
+    const isRequired = fieldOptions.validation?.rule.isRequired;
+    if (isRequired || fieldOptions.unique || fieldOptions.default !== void 0) {
+      migrationContent += ", col => col";
+      if (isRequired)
+        migrationContent += ".notNull()";
+      if (fieldOptions.unique)
+        migrationContent += ".unique()";
+      if (fieldOptions.default !== void 0)
+        if (typeof fieldOptions.default === "string")
+          migrationContent += `.defaultTo('${fieldOptions.default}')`;
+        else if (fieldOptions.default === null)
+          migrationContent += ".defaultTo(null)";
+        else
+          migrationContent += `.defaultTo(${fieldOptions.default})`;
+      migrationContent += "";
+    }
+    migrationContent += `)
+`;
+  }
+  if (twoFactorEnabled !== !1 && twoFactorEnabled)
+    migrationContent += `    .addColumn('two_factor_secret', 'text')
+`;
+  if (useBillable)
+    migrationContent += `    .addColumn('stripe_id', 'text')
+`;
+  if (useSoftDeletes)
+    migrationContent += `    .addColumn('deleted_at', 'timestamp')
+`;
+  if (usePasskey)
+    migrationContent += `    .addColumn('public_passkey', 'text')
+`;
+  if (otherModelRelations?.length)
+    for (const modelRelation of otherModelRelations) {
+      if (!modelRelation.foreignKey)
+        continue;
+      migrationContent += `    .addColumn('${modelRelation.foreignKey}', 'integer', (col) =>
+        col.references('${modelRelation.relationTable}.id').onDelete('cascade')
+      ) 
+`;
+    }
+  if (useTimestamps) {
+    migrationContent += "    .addColumn('created_at', 'timestamp', col => col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`))\n";
+    migrationContent += `    .addColumn('updated_at', 'timestamp')
+`;
+  }
+  migrationContent += `    .execute()
+
+`;
+  if (otherModelRelations?.length)
+    for (const modelRelation of otherModelRelations) {
+      if (!modelRelation.foreignKey)
+        continue;
+      migrationContent += generateForeignKeyIndexSQL(tableName, modelRelation.foreignKey);
+    }
+  if (model.indexes?.length) {
+    migrationContent += `
+`;
+    for (const index of model.indexes)
+      migrationContent += generateIndexCreationSQL(tableName, index);
+  }
+  migrationContent += generatePrimaryKeyIndexSQL(tableName);
+  if (useLikeable) {
+    const upvoteTable = getUpvoteTableName(model, tableName);
+    if (upvoteTable) {
+      const foreignKey = getLikeableForeignKey(model, tableName);
+      migrationContent += `
+  // Create upvote table
+`;
+      migrationContent += `  await (db as any).schema
+`;
+      migrationContent += `    .createTable('${upvoteTable}')
+`;
+      migrationContent += `    .addColumn('id', 'integer', col => col.primaryKey().autoIncrement())
+`;
+      migrationContent += `    .addColumn('${foreignKey}', 'integer', col => col.notNull())
+`;
+      migrationContent += `    .addColumn('user_id', 'integer', col => col.notNull())
+`;
+      migrationContent += "    .addColumn('created_at', 'timestamp', col => col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`))\n";
+      migrationContent += `    .addColumn('updated_at', 'timestamp')
+`;
+      migrationContent += `    .execute()
+
+`;
+      migrationContent += `  // Add indexes for upvote table
+`;
+      migrationContent += `  await (db as any).schema.createIndex('${upvoteTable}_${foreignKey}_index').on('${upvoteTable}').column('${foreignKey}').execute()
+`;
+      migrationContent += `  await (db as any).schema.createIndex('${upvoteTable}_user_${foreignKey}_unique').on('${upvoteTable}').columns(['user_id', '${foreignKey}']).unique().execute()
+`;
+      migrationContent += `  await (db as any).schema.createIndex('${upvoteTable}_id_index').on('${upvoteTable}').column('id').execute()
+`;
+    }
+  }
+  migrationContent += `}
+`;
+  const migrationFileName = `${new Date().getTime().toString()}-create-${tableName}-table.ts`, migrationFilePath = path.userMigrationsPath(migrationFileName);
+  await Bun.write(migrationFilePath, migrationContent);
+  log.success(`Created migration: ${italic(migrationFileName)}`);
+}
+async function createPivotTableMigration(model, modelPath) {
+  const pivotTables = await getPivotTables(model, modelPath);
+  if (!pivotTables.length)
+    return;
+  for (const pivotTable of pivotTables) {
+    if (await checkPivotMigration(pivotTable.table))
+      return;
+    let migrationContent = `import type { Database } from '@stacksjs/database'
+`;
+    migrationContent += `import { sql } from '@stacksjs/database'
+
+`;
+    migrationContent += `export async function up(db: Database<any>) {
+`;
+    migrationContent += `  await (db as any).schema
+`;
+    migrationContent += `    .createTable('${pivotTable.table}')
+`;
+    migrationContent += `    .addColumn('id', 'integer', col => col.primaryKey().autoIncrement())
+`;
+    migrationContent += `    .addColumn('${pivotTable.firstForeignKey}', 'integer')
+`;
+    migrationContent += `    .addColumn('${pivotTable.secondForeignKey}', 'integer')
+`;
+    migrationContent += `    .addColumn('created_at', 'timestamp', col => col.defaultTo(sql.raw('CURRENT_TIMESTAMP')))
+`;
+    migrationContent += `    .execute()
+`;
+    migrationContent += `    }
+`;
+    const migrationFileName = `${new Date().getTime().toString()}-create-${pivotTable.table}-table.ts`, migrationFilePath = path.userMigrationsPath(migrationFileName);
+    await Bun.write(migrationFilePath, migrationContent);
+    log.success(`Created pivot migration: ${migrationFileName}`);
+  }
+}
+async function createAlterTableMigration(modelPath) {
+  const model = (await import(modelPath)).default, modelName = getModelName(model, modelPath), tableName = getTableName(model, modelPath);
+  let hasChanged = !1;
+  const oldModel = (await import(path.frameworkPath(`cache/models/${modelName}.ts`))).default, lastFields = await getLastMigrationFields(modelName) ?? {}, currentFields = model.attributes, changes = pluckChanges(Object.keys(lastFields), Object.keys(currentFields)), fieldsToAdd = changes?.added || [], fieldsToRemove = changes?.removed || [];
+  let migrationContent = `import type { Database } from '@stacksjs/database'
+`;
+  migrationContent += `import { sql } from '@stacksjs/database'
+
+`;
+  migrationContent += `export async function up(db: Database<any>) {
+`;
+  if (fieldsToAdd.length || fieldsToRemove.length) {
+    hasChanged = !0;
+    migrationContent += `  await (db as any).schema.alterTable('${tableName}')
+`;
+  }
+  const fieldValidations = findDifferingKeys(lastFields, currentFields);
+  for (const fieldValidation of fieldValidations) {
+    hasChanged = !0;
+    const fieldNameFormatted = snakeCase(fieldValidation.key);
+    migrationContent += `await sql\`
+        ALTER TABLE ${tableName}
+        MODIFY COLUMN ${fieldNameFormatted} TEXT
+      \`.execute(db)
+
+`;
+  }
+  for (const fieldName of fieldsToAdd) {
+    const options = currentFields[fieldName], columnType = mapFieldTypeToColumnType(options.validation?.rule, "sqlite"), formattedFieldName = snakeCase(fieldName), isRequired = options.validation?.rule.isRequired;
+    migrationContent += `    .addColumn('${formattedFieldName}', ${columnType}`;
+    if (isRequired || options.unique || options.default !== void 0) {
+      migrationContent += ", col => col";
+      if (isRequired)
+        migrationContent += ".notNull()";
+      if (options.unique)
+        migrationContent += ".unique()";
+      if (options.default !== void 0)
+        if (typeof options.default === "string")
+          migrationContent += `.defaultTo('${options.default}')`;
+        else if (options.default === null)
+          migrationContent += ".defaultTo(null)";
+        else
+          migrationContent += `.defaultTo(${options.default})`;
+      migrationContent += "";
+    }
+    migrationContent += `)
+
+`;
+  }
+  for (const fieldName of fieldsToRemove)
+    migrationContent += `    .dropColumn('${fieldName}')
+`;
+  if (fieldsToAdd.length || fieldsToRemove.length)
+    migrationContent += `    .execute();
+`;
+  const lastFieldOrder = Object.values(lastFields).map((attr) => attr.order), currentFieldOrder = Object.values(currentFields).map((attr) => attr.order);
+  if (!isArrayEqual(lastFieldOrder, currentFieldOrder)) {
+    hasChanged = !0;
+    migrationContent += reArrangeColumns(model.attributes, tableName);
+  }
+  const oldIndexes = oldModel.indexes || [], newIndexes = model.indexes || [];
+  for (const oldIndex of oldIndexes)
+    if (!newIndexes.find((newIndex) => newIndex.name === oldIndex.name)) {
+      hasChanged = !0;
+      migrationContent += `  await (db as any).schema.dropIndex('${oldIndex.name}').execute()
+`;
+    }
+  for (const newIndex of newIndexes)
+    if (!oldIndexes.find((oldIndex) => oldIndex.name === newIndex.name)) {
+      hasChanged = !0;
+      migrationContent += generateIndexCreationSQL(tableName, newIndex);
+    }
+  migrationContent += `}
+`;
+  const migrationFileName = `${new Date().getTime().toString()}-update-${tableName}-table.ts`, migrationFilePath = path.userMigrationsPath(migrationFileName);
+  if (hasChanged) {
+    await Bun.write(migrationFilePath, migrationContent);
+    log.success(`Created migration: ${italic(migrationFileName)}`);
+  }
+}
+function reArrangeColumns(attributes, tableName) {
+  const fields = arrangeColumns(attributes);
+  let migrationContent = "", previousField = "";
+  for (const [fieldName] of fields) {
+    const fieldNameFormatted = snakeCase(fieldName);
+    if (previousField)
+      migrationContent += `await sql\`
+        ALTER TABLE ${tableName}
+        MODIFY COLUMN ${fieldNameFormatted} TEXT NOT NULL AFTER ${snakeCase(previousField)};
+      \`.execute(db)
+
+`;
+    previousField = fieldNameFormatted;
+  }
+  return migrationContent;
+}
+export function generateIndexCreationSQL(tableName, index) {
+  if (index.unique || index.where) {
+    const unique = index.unique ? "UNIQUE " : "", cols = index.columns.map((col) => snakeCase(col)).join(", "), whereClause = index.where ? ` WHERE ${index.where}` : "";
+    return `  await db.unsafe(\`CREATE ${unique}INDEX IF NOT EXISTS "${index.name}" ON "${tableName}" (${cols})${whereClause}\`).execute()
+`;
+  }
+  const columnsStr = index.columns.map((col) => `\`${snakeCase(col)}\``).join(", ");
+  return `  await (db as any).schema.createIndex('${index.name}').on('${tableName}').columns([${columnsStr}]).execute()
+`;
+}
+function generatePrimaryKeyIndexSQL(tableName) {
+  return `  await (db as any).schema.createIndex('${tableName}_id_index').on('${tableName}').column('id').execute()
+`;
+}
+function generateForeignKeyIndexSQL(tableName, foreignKey) {
+  return `  await (db as any).schema.createIndex('${tableName}_${foreignKey}_index').on('${tableName}').column(\`${foreignKey}\`).execute()
+
+`;
+}

package/dist/factory.d.ts

@@ -0,0 +1,41 @@
+import type { Attribute, Model } from '@stacksjs/types';
+import type { SeedResult } from './seeder';
+/**
+ * Build the internal `SeederModel`-shaped payload that `seedModelDirect`
+ * expects from a public-API call. Pure function — exported separately
+ * so tests can assert the override-precedence rules without touching
+ * the database.
+ *
+ * Precedence (lowest → highest): per-attribute `factory` output →
+ * global `options.with` → per-row `options.rows[i]`. All keys are
+ * snake-cased before insert so callers can use the model's camelCase
+ * attribute names without thinking about column naming.
+ */
+export declare function buildSeederPayload(modelInput: unknown, options?: GenerateOptions): {
+  name: string
+  table: string
+  count: number
+  fixtures: Array<Record<string, unknown>>
+  attributes: Record<string, Attribute>
+  model: Model
+};
+/**
+ * Generate factory rows for a model and insert them. Designed to be
+ * called from a class seeder.
+ *
+ * Honours the model's per-attribute `factory: faker => …` declarations
+ * — exactly the same code path as the legacy auto-walker — but without
+ * the implicit "every model with `useSeeder` fires on every run"
+ * coupling. See stacksjs/stacks#1919 for the rationale.
+ */
+export declare function generate(modelInput: unknown, options?: GenerateOptions): Promise<SeedResult>;
+export declare const factory: {
+  generate: typeof generate
+};
+export declare interface GenerateOptions {
+  count?: number
+  fresh?: boolean
+  verbose?: boolean
+  with?: Record<string, unknown>
+  rows?: Array<Record<string, unknown>>
+}

package/dist/factory.js

@@ -0,0 +1,51 @@
+import { log } from "@stacksjs/logging";
+import { seedModelDirect } from "./seeder";
+function resolveDefinition(input) {
+  if (input && typeof input === "object") {
+    const obj = input;
+    if (obj._definition && typeof obj._definition === "object" && "name" in obj._definition)
+      return obj._definition;
+    if ("name" in obj && (("attributes" in obj) || ("table" in obj) || ("traits" in obj)))
+      return obj;
+  }
+  throw Error("factory.generate: expected a Stacks model (the default export of app/Models/*.ts, or a defineModel() return value). Got something without a `.name` field.");
+}
+function snakeCase(str) {
+  return str.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z\d])([A-Z])/g, "$1_$2").replace(/(\d)([A-Za-z])/g, "$1_$2").toLowerCase();
+}
+function snakeCaseKeys(input) {
+  const out = {};
+  for (const [key, value] of Object.entries(input))
+    out[snakeCase(key)] = value;
+  return out;
+}
+export function buildSeederPayload(modelInput, options = {}) {
+  const def = resolveDefinition(modelInput), name = def.name, attributes = def.attributes ?? {}, useSeederConfig = def.traits?.useSeeder, seederDefault = useSeederConfig && typeof useSeederConfig === "object" ? useSeederConfig : void 0, count = options.count ?? seederDefault?.count ?? 10, globalOverrides = options.with ? snakeCaseKeys(options.with) : void 0, perRow = options.rows ?? seederDefault?.fixtures ?? [], fixtureCount = Math.max(count, perRow.length), fixtures = [];
+  for (let i = 0;i < fixtureCount; i++) {
+    const row = perRow[i];
+    if (!globalOverrides && !row)
+      continue;
+    fixtures[i] = { ...globalOverrides ?? {}, ...row ? snakeCaseKeys(row) : {} };
+  }
+  const table = def.table ?? `${snakeCase(name)}s`;
+  return { name, table, count: fixtureCount, fixtures, attributes, model: def };
+}
+export async function generate(modelInput, options = {}) {
+  const payload = buildSeederPayload(modelInput, options);
+  try {
+    return await seedModelDirect({
+      ...payload,
+      filePath: ""
+    }, {
+      fresh: options.fresh,
+      verbose: options.verbose ?? !1
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(`[factory] generate(${payload.name}) failed: ${message}`);
+    throw err;
+  }
+}
+export const factory = {
+  generate
+};

package/dist/fk-audit.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Glob, but resilient to "directory doesn't exist yet" (the userland
+ * `app/Models/` directory in particular often doesn't exist when the
+ * audit runs in framework tests or scaffolded apps that haven't
+ * created any models yet). Avoids the Bun Glob ENOENT.
+ */
+export declare function safeGlob(pattern: string): string[];
+/**
+ * Walk every model file (user + framework defaults) and return the
+ * full list of declared `belongsTo` foreign keys.
+ *
+ * Convention: `Comment` with `belongsTo: ['Post']` implies the FK
+ * `comments.post_id → posts.id`. Same shape the migration generator
+ * uses, so we keep it consistent here. Other relationship types
+ * (`hasOne`, `hasMany`, `belongsToMany` through tables) imply FKs in
+ * the *other* direction or in pivot tables — we only check
+ * `belongsTo` here for the simplest, highest-signal audit.
+ */
+export declare function getDeclaredFKs(): Promise<DeclaredFK[]>;
+/**
+ * Query the live database for every foreign key constraint, returning
+ * a normalised shape. Dialect-aware: PRAGMA on SQLite,
+ * information_schema on MySQL / PostgreSQL.
+ */
+export declare function getLiveFKs(): Promise<LiveFK[]>;
+/**
+ * Diff declared FKs against live FKs. Returns the declared FKs that
+ * have no matching row in the live database — these are the silent
+ * "FK should be enforcing referential integrity but isn't" cases that
+ * motivated this audit.
+ *
+ * Match key is `fromTable.fromColumn → toTable.toColumn` (case-
+ * insensitive). Extra live FKs (present in DB but not in any model)
+ * are not reported — those usually come from manual migrations or
+ * external tooling, both legitimate.
+ */
+export declare function auditForeignKeys(): Promise<FkAuditResult>;
+/**
+ * Scan the live database for rows whose foreign key references a
+ * parent row that doesn't exist. SQLite's `PRAGMA foreign_key_check`
+ * does this regardless of the `foreign_keys` pragma state and excludes
+ * NULL-FK rows. The violating column is resolved by joining the
+ * reported `fkid` against `PRAGMA foreign_key_list(table)`.
+ */
+export declare function findFkOrphans(dialect?: 'sqlite' | 'mysql' | 'postgres' | 'other'): Promise<FkOrphanReport>;
+// stacksjs/stacks#1916 — Foreign-key audit. Compares each model's
+// declared `belongsTo` relationships against the FKs that actually
+// exist in the live database. Drives `buddy doctor`'s FK integrity
+// check, surfaces the "you flipped DB_CONNECTION but the FKs didn't
+// follow" failure mode that motivated #1915 and #1916.
+//
+// Two halves:
+//
+//   1. Declared FKs: walk model files, look at `belongsTo`, compute
+//      the implied FK shape `{ fromTable, fromColumn, toTable,
+//      toColumn }`. Convention is `<related>_id` → `<related>.id`,
+//      same as the migration generator.
+//
+//   2. Live FKs: query the live database. SQLite via
+//      `PRAGMA foreign_key_list("…")`, MySQL/Postgres via
+//      `information_schema.key_column_usage`.
+export declare interface DeclaredFK {
+  fromTable: string
+  fromColumn: string
+  toTable: string
+  toColumn: string
+  model: string
+}
+export declare interface LiveFK {
+  fromTable: string
+  fromColumn: string
+  toTable: string
+  toColumn: string
+}
+export declare interface FkAuditResult {
+  declared: DeclaredFK[]
+  live: LiveFK[]
+  missing: DeclaredFK[]
+}
+// stacksjs/stacks#1951 — FK orphan detection. FK enforcement flipped
+// ON (utils.ts bootstrap pragmas) against databases that were written
+// while `foreign_keys = OFF`, so legacy rows can reference parents that
+// no longer exist. Those orphans silently turn previously-working
+// deletes/inserts into runtime FK failures. This READ-ONLY scan finds
+// them so `buddy doctor` can report before they bite.
+//
+// SQLite-specific: MySQL/Postgres enforce FKs natively, so the
+// FK-off-legacy-data failure mode can't arise there — we degrade to
+// `supported: false` rather than run an expensive per-FK anti-join.
+export declare interface FkOrphan {
+  table: string
+  column: string
+  parent: string
+  count: number
+  sampleRowids: number[]
+}
+export declare interface FkOrphanReport {
+  supported: boolean
+  total: number
+  orphans: FkOrphan[]
+}