@bolvrk/engine-sqlite 0.1.4

package/src/rules/schema-and-transactions.ts

@@ -0,0 +1,446 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Schema shape traps (STRICT, child-key indexes, nullable keys, dependent
+ * views and triggers) and transaction traps (deferred writes, nesting).
+ */
+import type { Finding } from "@bolvrk/engine";
+import {
+  alterActions,
+  constraintOf,
+  createdColumns,
+  dataTypeName,
+  descendants,
+  droppedTables,
+  hasWhere,
+  items,
+  nameOf,
+  pragmaIsOn,
+  pragmaOf,
+  tableConstraints,
+  tableCreatedInMigration,
+  tableOf,
+  tableOptions,
+} from "../helpers";
+import { sl020Meta, sl021Meta, sl022Meta, sl023Meta, sl024Meta, sl025Meta, sl026Meta, sl027Meta, sl028Meta, sl029Meta, sl030Meta } from "../metas/index";
+import { finding, type SlRule, type SlRuleContext } from "../rule";
+
+type AnyNode = Record<string, any>;
+type Stmt = SlRuleContext["migration"]["statements"][number];
+
+/** SL020: a new table without STRICT. */
+export const sl020: SlRule = {
+  meta: sl020Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt") continue;
+      // CREATE TABLE ... AS SELECT has no column list to be strict about; virtual tables have their own module rules.
+      if (createdColumns(stmt).length === 0) continue;
+      if (tableOptions(stmt).includes("STRICT")) continue;
+      const table = tableOf(stmt) ?? "";
+      out.push(
+        finding(sl020, stmt, {
+          title: `"${table}" is created without STRICT — column types are not enforced`,
+          message:
+            `Without STRICT, SQLite stores whatever value arrives regardless of the declared type: text in an INTEGER column, a number in a TEXT one. ` +
+            `Add STRICT now — it is a CREATE TABLE option only, and adding it later means rebuilding the table.`,
+          object: { table },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+interface ChildKey {
+  table: string;
+  columns: string[];
+  parent: string;
+  /** ON DELETE CASCADE declared on this key. */
+  cascade: boolean;
+}
+
+/** Foreign keys declared by a CREATE TABLE: column-level REFERENCES and table-level FOREIGN KEY. */
+function childKeys(stmt: Stmt): ChildKey[] {
+  if (stmt.node.type !== "create_table_stmt") return [];
+  const table = tableOf(stmt) ?? "";
+  const out: ChildKey[] = [];
+  for (const column of createdColumns(stmt)) {
+    const ref = constraintOf(column, "references_specification");
+    if (!ref) continue;
+    const spec = ref.type === "references_specification" ? ref : ref.constraint;
+    out.push({ table, columns: [nameOf(column.name) ?? ""], parent: nameOf(spec.table) ?? "", cascade: cascades(spec) });
+  }
+  for (const constraint of tableConstraints(stmt)) {
+    const fk = constraint.type === "constraint_foreign_key" ? constraint : constraint.constraint?.type === "constraint_foreign_key" ? constraint.constraint : undefined;
+    if (!fk) continue;
+    const spec = fk.references ?? fk;
+    out.push({
+      table,
+      columns: items(fk.columns).map((c: AnyNode) => nameOf(c) ?? ""),
+      parent: nameOf(spec.table) ?? "",
+      cascade: cascades(spec) || cascades(fk),
+    });
+  }
+  return out;
+}
+
+function cascades(spec: AnyNode): boolean {
+  return descendants(spec, (n) => n.type === "referential_action").some((action) => {
+    const words = descendants(action, (n) => n.type === "keyword").map((k) => String(k.name).toUpperCase());
+    return words.includes("DELETE") && words.includes("CASCADE");
+  });
+}
+
+/** Column lists of the indexes a migration creates on `table`, plus the unique/primary keys the table declares. */
+function indexedPrefixes(ctx: SlRuleContext, table: string): string[][] {
+  const out: string[][] = [];
+  for (const stmt of ctx.migration.statements) {
+    if (stmt.node.type === "create_index_stmt" && tableOf(stmt)?.toLowerCase() === table.toLowerCase()) {
+      out.push(items((stmt.node as AnyNode).columns).map((spec: AnyNode) => nameOf(spec.expr ?? spec) ?? ""));
+    }
+    if (stmt.node.type === "create_table_stmt" && tableOf(stmt)?.toLowerCase() === table.toLowerCase()) {
+      for (const column of createdColumns(stmt)) {
+        if (constraintOf(column, "constraint_primary_key") || constraintOf(column, "constraint_unique")) out.push([nameOf(column.name) ?? ""]);
+      }
+      for (const constraint of tableConstraints(stmt)) {
+        const inner = constraint.constraint ?? constraint;
+        if (inner.type === "constraint_primary_key" || inner.type === "constraint_unique") {
+          out.push(items(inner.columns).map((spec: AnyNode) => nameOf(spec.expr ?? spec) ?? ""));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function isPrefix(columns: string[], index: string[]): boolean {
+  return columns.every((column, i) => index[i]?.toLowerCase() === column.toLowerCase());
+}
+
+/** SL021: a child key without an index on its columns. */
+export const sl021: SlRule = {
+  meta: sl021Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      for (const key of childKeys(stmt)) {
+        if (indexedPrefixes(ctx, key.table).some((index) => isPrefix(key.columns, index))) continue;
+        out.push(
+          finding(sl021, stmt, {
+            title: `Foreign key "${key.table}"(${key.columns.join(", ")}) has no index`,
+            message:
+              `Every DELETE or UPDATE of a "${key.parent}" row scans all of "${key.table}" to check for references, because SQLite never indexes the child side of a foreign key. ` +
+              `Add CREATE INDEX on (${key.columns.join(", ")}) in this migration.`,
+            object: { table: key.table, column: key.columns[0] },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+/** SL022: RENAME while legacy_alter_table is on. */
+export const sl022: SlRule = {
+  meta: sl022Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    let legacy = false;
+    for (const stmt of ctx.migration.statements) {
+      const pragma = pragmaOf(stmt);
+      if (pragma?.name === "legacy_alter_table") {
+        legacy = pragmaIsOn(pragma.value);
+        continue;
+      }
+      if (!legacy) continue;
+      for (const action of alterActions(stmt)) {
+        if (action.type !== "alter_action_rename" && action.type !== "alter_action_rename_column") continue;
+        const table = tableOf(stmt) ?? "";
+        out.push(
+          finding(sl022, stmt, {
+            title: `Rename on "${table}" runs with legacy_alter_table on — views and triggers are not rewritten`,
+            message:
+              `PRAGMA legacy_alter_table=ON restores the pre-3.26 rename: any view or trigger that names the old identifier keeps naming it, and fails the first time it is used. ` +
+              `Switch the pragma off before renaming.`,
+            object: { table },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+interface Dependent {
+  kind: "view" | "trigger";
+  name: string;
+  /** Lower-cased identifiers the body mentions. */
+  identifiers: Set<string>;
+  /** The trigger's target table, lower-cased. */
+  target?: string;
+}
+
+/** Views and triggers created in this migration, in order, with the names their bodies mention. */
+function dependents(ctx: SlRuleContext, beforeIndex: number): Dependent[] {
+  const live = new Map<string, Dependent>();
+  for (const stmt of ctx.migration.statements) {
+    if (stmt.index >= beforeIndex) break;
+    const node = stmt.node as AnyNode;
+    if (node.type === "create_view_stmt" || node.type === "create_trigger_stmt") {
+      const kind = node.type === "create_view_stmt" ? "view" : "trigger";
+      const identifiers = new Set(descendants([node.clauses, node.body], (n) => n.type === "identifier").map((n) => String(n.name).toLowerCase()));
+      const target = kind === "trigger" ? nameOf(node.target?.table)?.toLowerCase() : undefined;
+      if (target) identifiers.add(target);
+      live.set(`${kind}:${(nameOf(node.name) ?? "").toLowerCase()}`, { kind, name: nameOf(node.name) ?? "", identifiers, target });
+    } else if (node.type === "drop_view_stmt") {
+      for (const view of items(node.views)) live.delete(`view:${(nameOf(view) ?? "").toLowerCase()}`);
+    } else if (node.type === "drop_trigger_stmt") {
+      live.delete(`trigger:${(nameOf(node.trigger) ?? "").toLowerCase()}`);
+    }
+  }
+  return [...live.values()];
+}
+
+/** SL023: DROP TABLE / DROP COLUMN of something a view or trigger created here still references. */
+export const sl023: SlRule = {
+  meta: sl023Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      for (const table of droppedTables(stmt)) {
+        const hit = dependents(ctx, stmt.index).find((d) => d.identifiers.has(table.toLowerCase()));
+        if (!hit) continue;
+        out.push(
+          finding(sl023, stmt, {
+            title: `DROP TABLE "${table}" breaks ${hit.kind} "${hit.name}" created in this migration`,
+            message:
+              hit.kind === "trigger" && hit.target === table.toLowerCase()
+                ? `Dropping the table drops the trigger with it — if that is the intent, drop the trigger explicitly so the migration says so.`
+                : `${hit.kind === "view" ? "The view" : "The trigger"} still names "${table}"; it fails the first time it is used. Drop or redefine it first.`,
+            object: { table },
+          }),
+        );
+      }
+      for (const action of alterActions(stmt)) {
+        if (action.type !== "alter_action_drop_column") continue;
+        const table = tableOf(stmt) ?? "";
+        const column = nameOf(action.column) ?? "";
+        const hit = dependents(ctx, stmt.index).find((d) => d.identifiers.has(table.toLowerCase()) && d.identifiers.has(column.toLowerCase()));
+        if (!hit) continue;
+        out.push(
+          finding(sl023, stmt, {
+            title: `DROP COLUMN "${column}" breaks ${hit.kind} "${hit.name}", which references it`,
+            message:
+              hit.kind === "view"
+                ? `The view keeps naming "${column}" and fails with "no such column" the first time it is queried (older SQLite releases refuse the DROP instead). Drop or redefine "${hit.name}" first.`
+                : `The trigger keeps naming "${column}", so every later write that fires it fails with "no such column" — writes to "${table}" break (older SQLite releases refuse the DROP instead). Drop or redefine "${hit.name}" first.`,
+            object: { table, column },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+/** SL024: a non-INTEGER PRIMARY KEY column in a rowid table without NOT NULL. */
+export const sl024: SlRule = {
+  meta: sl024Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt") continue;
+      if (tableOptions(stmt).includes("WITHOUT ROWID")) continue;
+      const table = tableOf(stmt) ?? "";
+      const keyed = new Set<string>();
+      for (const column of createdColumns(stmt)) if (constraintOf(column, "constraint_primary_key")) keyed.add(nameOf(column.name) ?? "");
+      for (const constraint of tableConstraints(stmt)) {
+        const inner = constraint.constraint ?? constraint;
+        if (inner.type === "constraint_primary_key") for (const spec of items(inner.columns)) keyed.add(nameOf(spec.expr ?? spec) ?? "");
+      }
+      for (const column of createdColumns(stmt)) {
+        const name = nameOf(column.name) ?? "";
+        if (!keyed.has(name)) continue;
+        if (constraintOf(column, "constraint_not_null")) continue;
+        // INTEGER PRIMARY KEY (single-column, ascending) is the rowid and can never be NULL.
+        const pk = constraintOf(column, "constraint_primary_key");
+        const direction = (pk?.direction ?? pk?.constraint?.direction)?.type;
+        if (pk && keyed.size === 1 && dataTypeName(column) === "INTEGER" && direction !== "sort_direction_desc") continue;
+        out.push(
+          finding(sl024, stmt, {
+            title: `PRIMARY KEY column "${name}" on "${table}" accepts NULL`,
+            message:
+              `A non-INTEGER primary key in a rowid table does not imply NOT NULL — SQLite keeps this old behaviour for compatibility — so NULL keys are accepted and each one counts as distinct. ` +
+              `Add NOT NULL to the column.`,
+            object: { table, column: name },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+const WRITE_TYPES = new Set([
+  "alter_table_stmt", "create_table_stmt", "create_index_stmt", "create_view_stmt", "create_trigger_stmt",
+  "drop_table_stmt", "drop_index_stmt", "drop_view_stmt", "drop_trigger_stmt", "insert_stmt", "update_stmt", "delete_stmt", "reindex_stmt",
+]);
+
+/** SL025: a plain (deferred) BEGIN followed by writes. */
+export const sl025: SlRule = {
+  meta: sl025Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const statements = ctx.migration.statements;
+    for (const stmt of statements) {
+      if (stmt.node.type !== "start_transaction_stmt") continue;
+      const behavior = String((stmt.node as AnyNode).behaviorKw?.name ?? "DEFERRED").toUpperCase();
+      if (behavior !== "DEFERRED") continue;
+      const writes = statements.some(
+        (later) =>
+          later.index > stmt.index &&
+          WRITE_TYPES.has(later.node.type) &&
+          !statements.some((end) => end.index > stmt.index && end.index < later.index && (end.node.type === "commit_transaction_stmt" || end.node.type === "rollback_transaction_stmt")),
+      );
+      if (!writes) continue;
+      out.push(
+        finding(sl025, stmt, {
+          title: "Write migration starts with a DEFERRED transaction",
+          message:
+            `A plain BEGIN takes no lock until the first write, then upgrades a read lock to a write lock — and a lock upgrade that finds another writer fails at once with SQLITE_BUSY, busy_timeout or not. ` +
+            `Use BEGIN IMMEDIATE for a migration that writes.`,
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL026: BEGIN inside an open transaction, or COMMIT/ROLLBACK with none open. */
+export const sl026: SlRule = {
+  meta: sl026Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    let open = false;
+    for (const stmt of ctx.migration.statements) {
+      const type = stmt.node.type;
+      if (type === "start_transaction_stmt") {
+        if (open) {
+          out.push(
+            finding(sl026, stmt, {
+              title: "BEGIN inside an open transaction fails",
+              message: `SQLite cannot nest transactions: this BEGIN fails with "cannot start a transaction within a transaction". Remove it, or use SAVEPOINT for a nested scope.`,
+            }),
+          );
+        }
+        open = true;
+      } else if (type === "commit_transaction_stmt" || type === "rollback_transaction_stmt") {
+        if (!open) {
+          out.push(
+            finding(sl026, stmt, {
+              title: `${type === "commit_transaction_stmt" ? "COMMIT" : "ROLLBACK"} with no open transaction fails`,
+              message: `Nothing is open at this point in the file, so SQLite answers "cannot ${type === "commit_transaction_stmt" ? "commit" : "rollback"} - no transaction is active". If the runner wraps the file, drop the statement; otherwise add the BEGIN.`,
+            }),
+          );
+        }
+        open = false;
+      }
+    }
+    return out;
+  },
+};
+
+/** SL027: DELETE without WHERE on a parent whose children (declared here) cascade. */
+export const sl027: SlRule = {
+  meta: sl027Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const cascading = ctx.migration.statements.flatMap(childKeys).filter((key) => key.cascade);
+    if (cascading.length === 0) return out;
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "delete_stmt" || hasWhere(stmt)) continue;
+      const table = tableOf(stmt) ?? "";
+      if (tableCreatedInMigration(ctx.migration, stmt.index, table)) continue;
+      const children = cascading.filter((key) => key.parent.toLowerCase() === table.toLowerCase()).map((key) => key.table);
+      if (children.length === 0) continue;
+      out.push(
+        finding(sl027, stmt, {
+          title: `DELETE FROM "${table}" with no WHERE also empties ${children.map((c) => `"${c}"`).join(", ")}`,
+          message:
+            `With foreign keys on, ON DELETE CASCADE removes every referencing row in ${children.join(", ")} in the same statement; with them off, nothing happens to those tables — the outcome depends on the runner's connection. ` +
+            `Add the predicate, batch it, and delete the children explicitly so the migration reads the way it behaves.`,
+          object: { table },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+const NON_DETERMINISTIC = new Set(["random", "randomblob", "changes", "total_changes", "last_insert_rowid", "sqlite_offset"]);
+
+/** SL028: CREATE INDEX over an expression that calls a non-deterministic function. */
+export const sl028: SlRule = {
+  meta: sl028Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_index_stmt") continue;
+      const calls = descendants((stmt.node as AnyNode).columns, (n) => n.type === "func_call")
+        .map((call) => String(nameOf(call.name) ?? "").toLowerCase())
+        .filter((name) => NON_DETERMINISTIC.has(name));
+      if (calls.length === 0) continue;
+      const table = tableOf(stmt) ?? "";
+      const index = nameOf((stmt.node as AnyNode).name);
+      out.push(
+        finding(sl028, stmt, {
+          title: `Index "${index}" uses ${calls[0]}() — SQLite refuses it`,
+          message: `An index expression must be deterministic; ${calls[0]}() is not, so CREATE INDEX fails ("non-deterministic functions prohibited in index expressions") and the migration stops. Index a deterministic expression or a stored column instead.`,
+          object: { table, index },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL029: AUTOINCREMENT on a WITHOUT ROWID table — the CREATE fails. */
+export const sl029: SlRule = {
+  meta: sl029Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt" || !tableOptions(stmt).includes("WITHOUT ROWID")) continue;
+      const column = createdColumns(stmt).find((c) => constraintOf(c, "constraint_auto_increment"));
+      if (!column) continue;
+      const table = tableOf(stmt) ?? "";
+      out.push(
+        finding(sl029, stmt, {
+          title: `AUTOINCREMENT on WITHOUT ROWID table "${table}" is refused`,
+          message: `A WITHOUT ROWID table has no rowid for AUTOINCREMENT to drive, so SQLite rejects the statement ("AUTOINCREMENT not allowed on WITHOUT ROWID tables") and the table is not created. Drop one of the two.`,
+          object: { table, column: nameOf(column.name) },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL030: ATTACH DATABASE inside a migration. */
+export const sl030: SlRule = {
+  meta: sl030Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "attach_database_stmt") continue;
+      out.push(
+        finding(sl030, stmt, {
+          title: "ATTACH DATABASE in a migration",
+          message: `This opens a second file by a machine-specific path on the runner's connection, for the life of that connection. Move the import into an operational job that takes the path as a parameter, and keep the migration to the schema.`,
+        }),
+      );
+    }
+    return out;
+  },
+};

package/src/rules/table-shape.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Whole-table effects of ALTER TABLE: the rewrite DROP COLUMN performs, and the deploy window a rename opens. */
+import type { Finding } from "@bolvrk/engine";
+import { alterActions, nameOf, tableCreatedInMigration, tableOf, tableRebuilds } from "../helpers";
+import { sl006Meta, sl007Meta } from "../metas/index";
+import { finding, type SlRule } from "../rule";
+
+/** SL006: DROP COLUMN rewrites the table (and fails if the column is referenced). */
+export const sl006: SlRule = {
+  meta: sl006Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      for (const action of alterActions(stmt)) {
+        if (action.type !== "alter_action_drop_column") continue;
+        const table = tableOf(stmt) ?? "";
+        if (table && tableCreatedInMigration(ctx.migration, stmt.index, table)) continue;
+        const column = nameOf(action.column);
+        out.push(
+          finding(sl006, stmt, {
+            title: `DROP COLUMN "${column}" rewrites every row of "${table}"`,
+            message:
+              `SQLite purges the column by rewriting the table's content in one write transaction — the single write lock is held for the whole copy, and every other writer waits. ` +
+              `The statement also fails if an index, foreign key, view, trigger or generated column still names "${column}". Remove code references first, drop dependent objects, and schedule the rewrite.`,
+            object: { table, column },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+/** SL007: RENAME COLUMN / RENAME TO breaks the previous release the moment it commits. */
+export const sl007: SlRule = {
+  meta: sl007Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      for (const action of alterActions(stmt)) {
+        const table = tableOf(stmt) ?? "";
+        if (action.type === "alter_action_rename_column") {
+          if (table && tableCreatedInMigration(ctx.migration, stmt.index, table)) continue;
+          const from = nameOf(action.oldName);
+          const to = nameOf(action.newName);
+          out.push(
+            finding(sl007, stmt, {
+              title: `RENAME COLUMN "${from}" → "${to}" on "${table}" breaks code still using the old name`,
+              message:
+                `The rename is instant; any process still running the previous release fails on "${from}" from the next statement it sends. ` +
+                `Expand and contract instead: add "${to}", dual-write, backfill, switch readers, drop "${from}" in a later release.`,
+              object: { table, column: from },
+            }),
+          );
+        } else if (action.type === "alter_action_rename") {
+          // A rename that finishes a rebuild (the dropped name comes back, onto a table this file created) is the documented recipe, not a deploy-window change.
+          // Renaming a table that already existed onto a dropped name is still a rename of that table: code using its old name breaks.
+          const to = nameOf(action.newName) ?? "";
+          const finishesRebuild = tableRebuilds(ctx.migration).some((r) => r.rename.index === stmt.index && r.replacementCreatedHere);
+          if (finishesRebuild) continue;
+          if (table && tableCreatedInMigration(ctx.migration, stmt.index, table)) continue;
+          out.push(
+            finding(sl007, stmt, {
+              title: `RENAME TABLE "${table}" → "${to}" breaks code still using the old name`,
+              message:
+                `The rename is instant; any process still running the previous release fails on "${table}" from the next statement it sends. ` +
+                `Create the new table and copy, and swap names only when no deployed code reads the old one.`,
+              object: { table },
+            }),
+          );
+        }
+      }
+    }
+    return out;
+  },
+};