@bolvrk/engine-sqlite 0.1.4

package/dist/metas/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `@bolvrk/engine-sqlite/metas` — RuleMeta objects ONLY. Nothing in this
+ * module may carry a `check` function or import the parser: the website
+ * bundles this entry into the browser to render the rule pages and the
+ * database filter. The implementations live in ../rules and import their
+ * meta from here, never the other way around. A test asserts no exported
+ * object has a `check` property.
+ *
+ * Every danger claim below is backed by the SQLite documentation named in
+ * the comment next to `verified`, and the "fails outright" claims are
+ * re-proven against a real SQLite in test/claims.test.ts.
+ */
+import type { RuleMeta } from "@bolvrk/engine";
+/** The SL corpus version. Bump on any rule addition, removal, or behavior change. */
+export declare const SL_RULE_CORPUS_VERSION = "0.4.0";
+export declare const sl001Meta: RuleMeta;
+export declare const sl002Meta: RuleMeta;
+export declare const sl003Meta: RuleMeta;
+export declare const sl004Meta: RuleMeta;
+export declare const sl005Meta: RuleMeta;
+export declare const sl006Meta: RuleMeta;
+export declare const sl007Meta: RuleMeta;
+export declare const sl008Meta: RuleMeta;
+export declare const sl009Meta: RuleMeta;
+export declare const sl010Meta: RuleMeta;
+export declare const sl011Meta: RuleMeta;
+export declare const sl012Meta: RuleMeta;
+export declare const sl013Meta: RuleMeta;
+export declare const sl014Meta: RuleMeta;
+export declare const sl015Meta: RuleMeta;
+export declare const sl016Meta: RuleMeta;
+export declare const sl017Meta: RuleMeta;
+export declare const sl018Meta: RuleMeta;
+export declare const sl019Meta: RuleMeta;
+export declare const sl020Meta: RuleMeta;
+export declare const sl021Meta: RuleMeta;
+export declare const sl022Meta: RuleMeta;
+export declare const sl023Meta: RuleMeta;
+export declare const sl024Meta: RuleMeta;
+export declare const sl025Meta: RuleMeta;
+export declare const sl026Meta: RuleMeta;
+export declare const sl027Meta: RuleMeta;
+export declare const sl028Meta: RuleMeta;
+export declare const sl029Meta: RuleMeta;
+export declare const sl030Meta: RuleMeta;
+export declare const sl031Meta: RuleMeta;
+export declare const sl032Meta: RuleMeta;
+export declare const sl033Meta: RuleMeta;
+export declare const sl034Meta: RuleMeta;
+export declare const sl035Meta: RuleMeta;
+/** Every SL meta, in corpus order. */
+export declare const sqliteMetas: readonly RuleMeta[];
+export declare const SQLITE_RULE_IDS: ReadonlySet<string>;

package/dist/metas/index.js

@@ -0,0 +1,80 @@
+import {
+  SL_RULE_CORPUS_VERSION,
+  SQLITE_RULE_IDS,
+  sl001Meta,
+  sl002Meta,
+  sl003Meta,
+  sl004Meta,
+  sl005Meta,
+  sl006Meta,
+  sl007Meta,
+  sl008Meta,
+  sl009Meta,
+  sl010Meta,
+  sl011Meta,
+  sl012Meta,
+  sl013Meta,
+  sl014Meta,
+  sl015Meta,
+  sl016Meta,
+  sl017Meta,
+  sl018Meta,
+  sl019Meta,
+  sl020Meta,
+  sl021Meta,
+  sl022Meta,
+  sl023Meta,
+  sl024Meta,
+  sl025Meta,
+  sl026Meta,
+  sl027Meta,
+  sl028Meta,
+  sl029Meta,
+  sl030Meta,
+  sl031Meta,
+  sl032Meta,
+  sl033Meta,
+  sl034Meta,
+  sl035Meta,
+  sqliteMetas
+} from "../index-m4sztshc.js";
+export {
+  SL_RULE_CORPUS_VERSION,
+  SQLITE_RULE_IDS,
+  sl001Meta,
+  sl002Meta,
+  sl003Meta,
+  sl004Meta,
+  sl005Meta,
+  sl006Meta,
+  sl007Meta,
+  sl008Meta,
+  sl009Meta,
+  sl010Meta,
+  sl011Meta,
+  sl012Meta,
+  sl013Meta,
+  sl014Meta,
+  sl015Meta,
+  sl016Meta,
+  sl017Meta,
+  sl018Meta,
+  sl019Meta,
+  sl020Meta,
+  sl021Meta,
+  sl022Meta,
+  sl023Meta,
+  sl024Meta,
+  sl025Meta,
+  sl026Meta,
+  sl027Meta,
+  sl028Meta,
+  sl029Meta,
+  sl030Meta,
+  sl031Meta,
+  sl032Meta,
+  sl033Meta,
+  sl034Meta,
+  sl035Meta,
+  sqliteMetas
+};

package/dist/parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SQLite parse layer: sql-parser-cst (MIT, pure TypeScript, a real
+ * dialect-aware grammar with source ranges). The only place SQLite SQL is
+ * turned into structure — rules walk the CST, never regex over SQL. Anything
+ * the grammar rejects fails the whole check: a partial check could hide a
+ * danger, so the engine reports "not checked" rather than guessing.
+ */
+import { type Node, type Statement } from "sql-parser-cst";
+export type { Node, Statement };
+export declare class SqliteMigrationParseError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface ParsedSqliteStatement {
+    /** 0-based position in the migration file (empty statements — a stray `;` — are skipped). */
+    index: number;
+    /** CST node type, e.g. "alter_table_stmt", "pragma_stmt". */
+    type: Statement["type"];
+    /** The statement node; rules descend from here. */
+    node: Statement;
+    /** Verbatim SQL text of this statement, trimmed. */
+    sql: string;
+    /** Character offset of the statement's start in the migration text. */
+    location: number;
+    /** Character offset one past the statement's end. */
+    end: number;
+}
+export interface ParsedSqliteMigration {
+    statements: ParsedSqliteStatement[];
+    /** sql-parser-cst version the tree came from. */
+    parserVersion: string;
+}
+export declare function parseSqliteMigration(sql: string): ParsedSqliteMigration;

package/dist/rule.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SL rule interface — the same shape as the Postgres engine's Rule
+ * (packages/engine/src/rule.ts) over the SQLite parse tree. Deliberately NOT
+ * shared code: the only shared abstractions between engines are the findings
+ * contract, the RuleMeta shape and the severity taxonomy.
+ */
+import type { Finding, RuleMeta } from "@bolvrk/engine";
+import type { ParsedSqliteMigration, ParsedSqliteStatement } from "./parser";
+export interface SlRuleContext {
+    migration: ParsedSqliteMigration;
+}
+export interface SlRule {
+    meta: RuleMeta;
+    check(ctx: SlRuleContext): Finding[];
+}
+/** Helper for building a finding with the rule's identity filled in. */
+export declare function finding(rule: SlRule, stmt: ParsedSqliteStatement, props: Omit<Finding, "ruleId" | "ruleVersion" | "tier" | "statementIndex" | "sql" | "severity"> & Partial<Pick<Finding, "severity">>): Finding;

package/dist/rules/add-column.d.ts

@@ -0,0 +1,13 @@
+import { type SlRule } from "../rule";
+/** SL001: NOT NULL with no default (or DEFAULT NULL) — the statement fails. */
+export declare const sl001: SlRule;
+/** SL002: PRIMARY KEY or UNIQUE on an added column — the statement fails. */
+export declare const sl002: SlRule;
+/** SL003: DEFAULT CURRENT_* or a parenthesised expression — the statement fails. */
+export declare const sl003: SlRule;
+/** SL004: GENERATED ... STORED on an added column — the statement fails. */
+export declare const sl004: SlRule;
+/** SL005: REFERENCES with a non-NULL default — fails whenever foreign keys are enforced. */
+export declare const sl005: SlRule;
+/** SL008: a CHECK constraint on an added column makes SQLite scan the whole table. */
+export declare const sl008: SlRule;

package/dist/rules/dml-and-maintenance.d.ts

@@ -0,0 +1,7 @@
+import { type SlRule } from "../rule";
+/** SL013: UPDATE / DELETE with no WHERE. */
+export declare const sl013: SlRule;
+/** SL014: VACUUM — an error inside a transaction, a whole-file rewrite outside one. */
+export declare const sl014: SlRule;
+/** SL015: REINDEX with no target. */
+export declare const sl015: SlRule;

package/dist/rules/index.d.ts

@@ -0,0 +1,5 @@
+import type { SlRule } from "../rule";
+export { SL_RULE_CORPUS_VERSION, SQLITE_RULE_IDS, sqliteMetas } from "../metas/index";
+export type { SlRule, SlRuleContext } from "../rule";
+/** The SL corpus, in id order. */
+export declare const allSqliteRules: readonly SlRule[];

package/dist/rules/indexes-and-types.d.ts

@@ -0,0 +1,7 @@
+import { type SlRule } from "../rule";
+/** SL016: CREATE INDEX on a table that already exists — built under the write lock, no CONCURRENTLY. */
+export declare const sl016: SlRule;
+/** SL017: a PRIMARY KEY column that is not exactly `INTEGER` (or is `INTEGER ... DESC`) in a rowid table. */
+export declare const sl017: SlRule;
+/** SL018: AUTOINCREMENT. */
+export declare const sl018: SlRule;

package/dist/rules/performance.d.ts

@@ -0,0 +1,11 @@
+import { type SlRule } from "../rule";
+/** SL031: an index the planner will never prefer over what already exists. */
+export declare const sl031: SlRule;
+/** SL032: CREATE INDEX on a new table before the INSERT ... SELECT that fills it. */
+export declare const sl032: SlRule;
+/** SL033: TEXT/BLOB primary key on a rowid table. */
+export declare const sl033: SlRule;
+/** SL034: journal_mode set to a rollback mode. */
+export declare const sl034: SlRule;
+/** SL035: a pragma that only affects the runner's connection. */
+export declare const sl035: SlRule;

package/dist/rules/rebuild-pragmas.d.ts

@@ -0,0 +1,11 @@
+import { type SlRule } from "../rule";
+/** SL009: the rebuild recipe without PRAGMA foreign_keys=OFF before it. */
+export declare const sl009: SlRule;
+/** SL010: PRAGMA foreign_keys / journal_mode after BEGIN — silently ignored. */
+export declare const sl010: SlRule;
+/** SL011: foreign keys switched off and never back on in this file. */
+export declare const sl011: SlRule;
+/** SL012: foreign keys re-enabled without PRAGMA foreign_key_check in between. */
+export declare const sl012: SlRule;
+/** SL019: the rebuild recipe with the copy step missing — the old table is dropped before its rows reach the new one. */
+export declare const sl019: SlRule;

package/dist/rules/schema-and-transactions.d.ts

@@ -0,0 +1,23 @@
+import { type SlRule } from "../rule";
+/** SL020: a new table without STRICT. */
+export declare const sl020: SlRule;
+/** SL021: a child key without an index on its columns. */
+export declare const sl021: SlRule;
+/** SL022: RENAME while legacy_alter_table is on. */
+export declare const sl022: SlRule;
+/** SL023: DROP TABLE / DROP COLUMN of something a view or trigger created here still references. */
+export declare const sl023: SlRule;
+/** SL024: a non-INTEGER PRIMARY KEY column in a rowid table without NOT NULL. */
+export declare const sl024: SlRule;
+/** SL025: a plain (deferred) BEGIN followed by writes. */
+export declare const sl025: SlRule;
+/** SL026: BEGIN inside an open transaction, or COMMIT/ROLLBACK with none open. */
+export declare const sl026: SlRule;
+/** SL027: DELETE without WHERE on a parent whose children (declared here) cascade. */
+export declare const sl027: SlRule;
+/** SL028: CREATE INDEX over an expression that calls a non-deterministic function. */
+export declare const sl028: SlRule;
+/** SL029: AUTOINCREMENT on a WITHOUT ROWID table — the CREATE fails. */
+export declare const sl029: SlRule;
+/** SL030: ATTACH DATABASE inside a migration. */
+export declare const sl030: SlRule;

package/dist/rules/table-shape.d.ts

@@ -0,0 +1,5 @@
+import { type SlRule } from "../rule";
+/** SL006: DROP COLUMN rewrites the table (and fails if the column is referenced). */
+export declare const sl006: SlRule;
+/** SL007: RENAME COLUMN / RENAME TO breaks the previous release the moment it commits. */
+export declare const sl007: SlRule;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bolvrk/engine-sqlite",
+  "version": "0.1.4",
+  "description": "Bolvrk SQLite migration danger rules (SL###) over a real SQLite grammar. ALPHA — static rules only, behind --engine=sqlite in the CLI.",
+  "license": "(FSL-1.1-ALv2 AND Apache-2.0)",
+  "homepage": "https://bolvrk.com",
+  "repository": "github:bolvrk/bolvrk",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./metas": {
+      "types": "./dist/metas/index.d.ts",
+      "bun": "./src/metas/index.ts",
+      "import": "./dist/metas/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && bun build src/index.ts src/metas/index.ts --outdir dist --target node --external @bolvrk/engine --external sql-parser-cst --splitting && tsc -p tsconfig.build.json",
+    "docs": "bun scripts/gen-rule-docs.ts"
+  },
+  "dependencies": {
+    "sql-parser-cst": "0.42.1"
+  },
+  "peerDependencies": {
+    "@bolvrk/engine": "^0.1.4"
+  },
+  "devDependencies": {},
+  "keywords": [
+    "sqlite",
+    "migrations",
+    "sql",
+    "lint",
+    "ddl"
+  ]
+}

package/src/engine.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+import {
+  applySuppressions,
+  collectSuppressions,
+  CONTRACT_VERSION,
+  scanSecrets,
+  sortFindings,
+  type CheckReport,
+  type Finding,
+  type ParsedMigration,
+} from "@bolvrk/engine";
+import packageJson from "../package.json";
+import { parseSqliteMigration } from "./parser";
+import type { SlRule } from "./rule";
+import { allSqliteRules, SL_RULE_CORPUS_VERSION, SQLITE_RULE_IDS } from "./rules/index";
+
+export interface SqliteCheckOptions {
+  /** Override the rule set (used by tests); defaults to the full SL corpus. */
+  rules?: readonly SlRule[];
+  /** Skip the credential rules (BC003, BC004) that `check` runs on every engine. Default: run them. */
+  skipCredentials?: boolean;
+}
+
+/** The credential rules `bolvrk check` runs on Postgres and, through here, on SQLite too — text-level, engine-neutral. */
+export const CREDENTIAL_RULE_IDS: ReadonlySet<string> = new Set(["BC003", "BC004"]);
+
+/**
+ * Credential findings come from the engine's line scanner. Re-anchor each to
+ * the SQLite statement that contains its line so the finding follows the
+ * statement contract (statementIndex, statement SQL) — with the secret
+ * masked, as the scanner masked it.
+ */
+function credentialFindings(sql: string, migration: ReturnType<typeof parseSqliteMigration>): Finding[] {
+  const report = scanSecrets(sql);
+  if (report.findings.length === 0) return [];
+  const lineStarts: number[] = [0];
+  for (let i = 0; i < sql.length; i++) if (sql.charCodeAt(i) === 10) lineStarts.push(i + 1);
+  const lines = sql.split(/\r?\n/);
+  const out: Finding[] = [];
+  for (const hit of report.findings) {
+    if (!CREDENTIAL_RULE_IDS.has(hit.ruleId)) continue;
+    const offset = lineStarts[hit.statementIndex] ?? -1;
+    const stmt = migration.statements.find((s) => offset >= s.location && offset < s.end);
+    if (!stmt) continue;
+    const original = lines[hit.statementIndex] ?? "";
+    out.push({ ...hit, statementIndex: stmt.index, sql: original ? stmt.sql.replace(original.trim(), hit.sql.trim()) : stmt.sql });
+  }
+  return out;
+}
+
+/**
+ * Run a SQLite migration through the SL corpus. Same findings contract as
+ * the Postgres engine, same determinism guarantee: identical input produces
+ * byte-identical report JSON. Static (tier 1) only — SQLite has no server
+ * to introspect, and the rules that would want a live file (table sizes)
+ * say so in their message instead.
+ *
+ * Inline suppressions (`-- bolvrk-ignore SL001: reason`) work exactly as on
+ * Postgres: the engine's own collector reads the comment lines between
+ * statements as the parser located them.
+ */
+export function checkSqliteMigration(sql: string, options: SqliteCheckOptions = {}): CheckReport {
+  const migration = parseSqliteMigration(sql);
+  const rules = options.rules ?? allSqliteRules;
+  const raw = [...rules.flatMap((rule) => rule.check({ migration })), ...(options.skipCredentials ? [] : credentialFindings(sql, migration))];
+  // The suppression collector only reads index/location/end of each statement.
+  const suppressions = collectSuppressions(sql, migration as unknown as ParsedMigration, new Set([...SQLITE_RULE_IDS, ...CREDENTIAL_RULE_IDS]));
+  const findings = sortFindings(applySuppressions(raw, suppressions));
+  return {
+    contractVersion: CONTRACT_VERSION,
+    engine: "sqlite",
+    engineVersion: packageJson.version,
+    ruleCorpusVersion: SL_RULE_CORPUS_VERSION,
+    schemaInspected: false,
+    statementCount: migration.statements.length,
+    findings,
+    ...(suppressions.length > 0 ? { suppressions } : {}),
+  };
+}
+
+/** 1-based start line of each statement — for SARIF locations. */
+export function sqliteStatementStartLines(sql: string): number[] {
+  const migration = parseSqliteMigration(sql);
+  return migration.statements.map((stmt) => {
+    let line = 1;
+    for (let i = 0; i < stmt.location; i++) if (sql.charCodeAt(i) === 10) line++;
+    return line;
+  });
+}

package/src/helpers.ts

@@ -0,0 +1,254 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CST helpers the SL rules are written against: one implementation of
+ * "which table does this statement touch", "is this statement inside an
+ * explicit transaction", and the shape of a column definition.
+ */
+import type { Node } from "sql-parser-cst";
+import type { ParsedSqliteMigration, ParsedSqliteStatement } from "./parser";
+
+type AnyNode = Record<string, any>;
+
+/** Unquoted name of an identifier or a `schema.name` member expression. */
+export function nameOf(node: AnyNode | undefined | null): string | undefined {
+  if (!node) return undefined;
+  if (node.type === "identifier") return node.name as string;
+  if (node.type === "member_expr") return nameOf(node.property);
+  if (node.type === "keyword") return String(node.name).toLowerCase();
+  return undefined;
+}
+
+/** Items of a `list_expr`, or the single node when the parser did not wrap one. */
+export function items(node: AnyNode | undefined | null): AnyNode[] {
+  if (!node) return [];
+  if (node.type === "list_expr") return node.items ?? [];
+  if (node.type === "paren_expr") return items(node.expr);
+  return [node];
+}
+
+/** The ALTER TABLE actions of a statement (empty for anything else). */
+export function alterActions(stmt: ParsedSqliteStatement): AnyNode[] {
+  if (stmt.node.type !== "alter_table_stmt") return [];
+  return items((stmt.node as AnyNode).actions);
+}
+
+/** Column definitions added by `ALTER TABLE ... ADD [COLUMN]` in this statement. */
+export function addedColumns(stmt: ParsedSqliteStatement): AnyNode[] {
+  return alterActions(stmt)
+    .filter((action) => action.type === "alter_action_add_column")
+    .map((action) => action.column)
+    .filter((column) => column?.type === "column_definition");
+}
+
+/** Column definitions of a CREATE TABLE statement (constraints declared at table level excluded). */
+export function createdColumns(stmt: ParsedSqliteStatement): AnyNode[] {
+  if (stmt.node.type !== "create_table_stmt") return [];
+  return items((stmt.node as AnyNode).columns).filter((item) => item.type === "column_definition");
+}
+
+/** Table-level constraints of a CREATE TABLE statement. */
+export function tableConstraints(stmt: ParsedSqliteStatement): AnyNode[] {
+  if (stmt.node.type !== "create_table_stmt") return [];
+  return items((stmt.node as AnyNode).columns).filter((item) => item.type !== "column_definition");
+}
+
+/** A column definition's constraint of the given CST type, if any. */
+export function constraintOf(column: AnyNode, type: string): AnyNode | undefined {
+  return (column.constraints ?? []).find((c: AnyNode) => c.type === type || c.constraint?.type === type);
+}
+
+/** Keyword name(s) of a data type node, uppercased and joined — `INT`, `INTEGER`, `VARCHAR`. */
+export function dataTypeName(column: AnyNode): string {
+  const name = column.dataType?.name;
+  if (!name) return "";
+  const parts = Array.isArray(name) ? name : [name];
+  return parts.map((part: AnyNode) => String(part?.name ?? part?.text ?? "")).join(" ").toUpperCase();
+}
+
+/** Table options of CREATE TABLE (`WITHOUT ROWID`, `STRICT`), uppercased. */
+export function tableOptions(stmt: ParsedSqliteStatement): string[] {
+  if (stmt.node.type !== "create_table_stmt") return [];
+  return items((stmt.node as AnyNode).options)
+    .filter((option) => option.type === "table_option")
+    .map((option) => (Array.isArray(option.name) ? option.name : [option.name]).map((kw: AnyNode) => String(kw?.name ?? "")).join(" ").toUpperCase());
+}
+
+/** The primary table a statement targets, if any. */
+export function tableOf(stmt: ParsedSqliteStatement): string | undefined {
+  const node = stmt.node as AnyNode;
+  switch (node.type) {
+    case "alter_table_stmt":
+    case "create_index_stmt":
+      return nameOf(node.table);
+    case "create_table_stmt":
+    case "create_view_stmt":
+      return nameOf(node.name);
+    case "drop_table_stmt":
+      return nameOf(items(node.tables)[0]);
+    case "insert_stmt":
+      return nameOf(node.clauses?.find((c: AnyNode) => c.type === "insert_clause")?.table);
+    case "update_stmt":
+      return nameOf(items(node.clauses?.find((c: AnyNode) => c.type === "update_clause")?.tables)[0]);
+    case "delete_stmt":
+      return nameOf(items(node.clauses?.find((c: AnyNode) => c.type === "delete_clause")?.tables)[0]);
+    default:
+      return undefined;
+  }
+}
+
+/** Tables dropped by a DROP TABLE statement. */
+export function droppedTables(stmt: ParsedSqliteStatement): string[] {
+  if (stmt.node.type !== "drop_table_stmt") return [];
+  return items((stmt.node as AnyNode).tables).map(nameOf).filter((n): n is string => !!n);
+}
+
+/** True when `table` is created by an earlier statement of this migration. */
+export function tableCreatedInMigration(migration: ParsedSqliteMigration, beforeIndex: number, table: string): boolean {
+  const wanted = table.toLowerCase();
+  return migration.statements.some(
+    (stmt) => stmt.index < beforeIndex && stmt.node.type === "create_table_stmt" && tableOf(stmt)?.toLowerCase() === wanted,
+  );
+}
+
+/** One "drop, then rename another table onto the name" pair in a migration. */
+export interface TableRebuild {
+  /** The DROP TABLE statement. */
+  drop: ParsedSqliteStatement;
+  /** The ALTER TABLE ... RENAME TO statement that restores the dropped name. */
+  rename: ParsedSqliteStatement;
+  /** The name being rebuilt. */
+  table: string;
+  /** The table renamed onto it. */
+  replacement: string;
+  /** True when the replacement was created earlier in this file — the documented recipe rather than a swap of two live tables. */
+  replacementCreatedHere: boolean;
+  /** An INSERT into the replacement that reads from the old table, issued before the DROP. */
+  copy?: ParsedSqliteStatement;
+}
+
+/**
+ * Every rebuild in the migration: DROP TABLE x followed, later in the file,
+ * by ALTER TABLE y RENAME TO x. The interim table's name plays no part —
+ * the match is structural, on the dropped name coming back as a rename
+ * target. Cross-file rebuilds are invisible; the engine sees one file.
+ */
+export function tableRebuilds(migration: ParsedSqliteMigration): TableRebuild[] {
+  const out: TableRebuild[] = [];
+  for (const drop of migration.statements) {
+    for (const table of droppedTables(drop)) {
+      const wanted = table.toLowerCase();
+      const rename = migration.statements.find(
+        (later) =>
+          later.index > drop.index &&
+          alterActions(later).some((a) => a.type === "alter_action_rename" && String(nameOf(a.newName) ?? "").toLowerCase() === wanted),
+      );
+      if (!rename) continue;
+      const replacement = tableOf(rename) ?? "";
+      const copy = migration.statements.find(
+        (stmt) =>
+          stmt.index < drop.index &&
+          stmt.node.type === "insert_stmt" &&
+          tableOf(stmt)?.toLowerCase() === replacement.toLowerCase() &&
+          readsFromTable(stmt, table),
+      );
+      out.push({ drop, rename, table, replacement, replacementCreatedHere: !!replacement && tableCreatedInMigration(migration, rename.index, replacement), copy });
+    }
+  }
+  return out;
+}
+
+/** True when a table name appears anywhere in the statement other than as its own target — a FROM, a join, a subquery. */
+function readsFromTable(stmt: ParsedSqliteStatement, table: string): boolean {
+  const wanted = table.toLowerCase();
+  const node = stmt.node as AnyNode;
+  const sources = (node.clauses ?? []).filter((c: AnyNode) => c.type !== "insert_clause");
+  return descendants(sources, (n) => n.type === "identifier" && String(n.name).toLowerCase() === wanted).length > 0;
+}
+
+/** The WHERE clause of an UPDATE / DELETE, if present. */
+export function hasWhere(stmt: ParsedSqliteStatement): boolean {
+  const clauses: AnyNode[] = (stmt.node as AnyNode).clauses ?? [];
+  return clauses.some((c) => c.type === "where_clause");
+}
+
+export interface PragmaRead {
+  name: string;
+  /** Assigned value, lowercased (`off`, `on`, `0`, `wal`); undefined for a bare query like `PRAGMA foreign_key_check`. */
+  value?: string;
+}
+
+/** Name and value of a PRAGMA statement; undefined for anything else. */
+export function pragmaOf(stmt: ParsedSqliteStatement): PragmaRead | undefined {
+  if (stmt.node.type !== "pragma_stmt") return undefined;
+  const pragma = (stmt.node as AnyNode).pragma;
+  if (!pragma) return undefined;
+  if (pragma.type === "pragma_assignment") return { name: nameOf(pragma.name)!.toLowerCase(), value: literalText(pragma.value) };
+  if (pragma.type === "pragma_func_call") {
+    const arg = pragma.args?.expr;
+    return { name: nameOf(pragma.name)!.toLowerCase(), value: arg ? literalText(arg) : undefined };
+  }
+  const name = nameOf(pragma);
+  return name ? { name: name.toLowerCase() } : undefined;
+}
+
+function literalText(node: AnyNode | undefined): string | undefined {
+  if (!node) return undefined;
+  // A negative number (`PRAGMA cache_size = -64000`) parses as a prefix operator over the literal.
+  if (node.type === "prefix_op_expr" && node.expr) return `${String(node.operator ?? "")}${literalText(node.expr) ?? ""}`;
+  if (node.type === "keyword") return String(node.name).toLowerCase();
+  if (node.type === "identifier") return String(node.name).toLowerCase();
+  if ("value" in node && node.value !== undefined && node.value !== null) return String(node.value).toLowerCase();
+  if (node.text) return String(node.text).toLowerCase();
+  return undefined;
+}
+
+/** SQLite's boolean spellings for a pragma value. */
+export function pragmaIsOff(value: string | undefined): boolean {
+  return value !== undefined && ["off", "0", "false", "no"].includes(value);
+}
+export function pragmaIsOn(value: string | undefined): boolean {
+  return value !== undefined && ["on", "1", "true", "yes"].includes(value);
+}
+
+/**
+ * For each statement, whether it runs inside an explicit transaction opened
+ * earlier in the file (BEGIN ... COMMIT/END/ROLLBACK). Statements before any
+ * BEGIN, or after the matching COMMIT, are "autocommit" from the file's point
+ * of view — a migration runner may still wrap the whole file, which is why
+ * rules that depend on this say so in their message.
+ */
+export function insideTransaction(migration: ParsedSqliteMigration): boolean[] {
+  const out: boolean[] = [];
+  let open = false;
+  for (const stmt of migration.statements) {
+    const type = stmt.node.type;
+    if (type === "start_transaction_stmt") {
+      out.push(false);
+      open = true;
+      continue;
+    }
+    if (type === "commit_transaction_stmt" || type === "rollback_transaction_stmt") {
+      out.push(open);
+      open = false;
+      continue;
+    }
+    out.push(open);
+  }
+  return out;
+}
+
+/** Depth-first descendants of a CST node matching a predicate. */
+export function descendants(node: Node | AnyNode | undefined, predicate: (node: AnyNode) => boolean): AnyNode[] {
+  const out: AnyNode[] = [];
+  const walk = (value: any) => {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item);
+      return;
+    }
+    if (value.type && predicate(value)) out.push(value);
+    for (const key of Object.keys(value)) if (key !== "range" && typeof value[key] === "object") walk(value[key]);
+  };
+  walk(node);
+  return out;
+}