migraguard 0.3.1 → 0.4.1

package/COMMANDS.md

@@ -64,7 +64,27 @@ migraguard check
 
 ### `migraguard lint`
 
-Run Squawk lint on migration files to detect idempotency and safety rule violations.
+Run built-in safety rules on all migration files. Rules use libpg-query AST analysis — no external tools required.
+
+Rules (all enabled by default):
+- `require-if-not-exists` — CREATE/DROP must use IF NOT EXISTS / IF EXISTS
+- `require-concurrent-index` — CREATE INDEX must use CONCURRENTLY (skipped for tables created in the same file)
+- `require-lock-timeout` — SET lock_timeout must appear before DDL statements
+- `ban-concurrent-index-in-transaction` — CONCURRENTLY cannot be inside BEGIN...COMMIT
+- `adding-not-nullable-field` — NOT NULL column must have a DEFAULT value
+- `constraint-missing-not-valid` — ADD CONSTRAINT must use NOT VALID
+
+Disable specific rules or add custom rules via config:
+```json
+{
+  "lint": {
+    "rules": { "require-lock-timeout": false },
+    "customRulesDir": "lint-rules"
+  }
+}
+```
+
+Custom rule files (`.js` / `.mjs`) in the specified directory are loaded automatically. Each file must default-export a `LintRule` object. See README for an example.
 
 ```bash
 migraguard lint

package/README.md

@@ -1,5 +1,7 @@
 # migraguard
 
+[![npm version](https://badge.fury.io/js/migraguard.svg)](https://www.npmjs.com/package/migraguard) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 An incident-prevention migration tool for PostgreSQL. Enforces safe operational policies via CI gates and DB state tracking, so that common migration accidents are structurally impossible.
 
 **Prevented accidents:**
@@ -48,11 +50,7 @@ npx migraguard dump
 - **One release = one file**: Migration files are squashed into a single file before release, simplifying error recovery. In DAG mode, independent DDL can be released individually
 - **Parallel releases via dependency tree**: DDL dependencies are analyzed to build a DAG, enabling parallel releases for independent changes
 - **Shift verification left**: Linting, checksum-based tamper detection, and schema dump diffs run at the PR stage
-- **Minimal footprint**: The runtime depends on four external tools with clear responsibilities:
-  - `psql` — executes migration SQL
-  - `pg_dump` — produces schema dumps for drift detection
-  - [Squawk](https://squawkhq.com/) — lints SQL for safety (optional)
-  - [libpg-query](https://github.com/pganalyze/libpg-query) — parses DDL for dependency analysis (DAG model)
+- **Minimal footprint**: Two CLI tools (`psql`, `pg_dump`) and one npm library ([libpg-query](https://github.com/pganalyze/libpg-query)). No external linter required — lint rules are built in via AST analysis
 
 ## Core Concepts
 
@@ -157,7 +155,7 @@ See [docs/state-model.md](docs/state-model.md) for detailed apply, check, resolv
 | `status` | Display migration status per file |
 | `editable` | List currently editable files (tail / leaf) |
 | `check` | Verify file integrity via metadata.json (no DB required) |
-| `lint` | SQL lint via Squawk |
+| `lint` | Run built-in safety rules (AST-based) |
 | `verify` / `verify --all` | Prove idempotency on shadow DB |
 | `dump` | Save normalized schema dump |
 | `diff` | Show schema diff (DB vs saved dump) |
@@ -242,7 +240,14 @@ jobs:
     "excludePrivileges": true
   },
   "lint": {
-    "squawk": true
+    "rules": {
+      "require-concurrent-index": true,
+      "require-if-not-exists": true,
+      "require-lock-timeout": true,
+      "ban-concurrent-index-in-transaction": true,
+      "adding-not-nullable-field": true,
+      "constraint-missing-not-valid": true
+    }
   }
 }
 ```
@@ -309,7 +314,20 @@ CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);
 UPDATE users SET status = 'active' WHERE status IS NULL;
 ```
 
-For safe DDL patterns (lock timeout, CONCURRENTLY, batch backfills), see [docs/safe-ddl.md](docs/safe-ddl.md).
+`migraguard lint` enforces these patterns with built-in rules (no external tools required):
+
+| Rule | Detects |
+|------|---------|
+| `require-if-not-exists` | CREATE/DROP without IF NOT EXISTS / IF EXISTS |
+| `require-concurrent-index` | CREATE INDEX without CONCURRENTLY on existing tables |
+| `require-lock-timeout` | DDL without prior SET lock_timeout |
+| `ban-concurrent-index-in-transaction` | CONCURRENTLY inside BEGIN...COMMIT |
+| `adding-not-nullable-field` | NOT NULL column without DEFAULT |
+| `constraint-missing-not-valid` | ADD CONSTRAINT without NOT VALID |
+
+Rules are enabled by default and can be disabled per-rule in `migraguard.config.json` under `lint.rules`.
+
+Project-specific rules can be added via `lint.customRulesDir`. See [docs/safe-ddl.md](docs/safe-ddl.md) for built-in rule details and custom rule examples.
 
 ## Directory Structure
 
@@ -422,8 +440,8 @@ No. `verify` creates a temporary shadow DB, applies migrations twice, then drops
 | Language | TypeScript (Node.js) |
 | DB execution | `psql` CLI |
 | Schema dump | `pg_dump --schema-only` |
-| SQL lint | [Squawk](https://squawkhq.com/) |
-| SQL parser | [libpg-query](https://github.com/pganalyze/libpg-query) (PostgreSQL real parser WASM build, for DDL dependency analysis) |
+| SQL lint | Built-in rules via [libpg-query](https://github.com/pganalyze/libpg-query) AST analysis |
+| SQL parser | [libpg-query](https://github.com/pganalyze/libpg-query) (PostgreSQL real parser WASM build) |
 | Package manager | npm |
 
 ## Detailed Documentation

package/dist/cli.js

@@ -1,19 +1,21 @@
 import { Command } from 'commander';
 import chalk6 from 'chalk';
+import { createRequire } from 'module';
 import { readFile, mkdir, writeFile, unlink, readdir } from 'fs/promises';
 import { dirname, resolve, join } from 'path';
 import { existsSync } from 'fs';
 import { randomBytes, createHash } from 'crypto';
 import libpg from 'libpg-query';
+import { pathToFileURL } from 'url';
+import pg from 'pg';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import pg from 'pg';
 import { tmpdir } from 'os';
 
 // src/cli/index.ts
-
-// src/index.ts
-var VERSION = "0.2.2";
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var VERSION = pkg.version;
 var CONFIG_FILE_NAME = "migraguard.config.json";
 var DEFAULT_NAMING = {
   pattern: "{timestamp}__{description}.sql",
@@ -33,7 +35,14 @@ var DEFAULT_DUMP = {
   excludePrivileges: true
 };
 var DEFAULT_LINT = {
-  squawk: true
+  rules: {
+    "require-concurrent-index": true,
+    "require-if-not-exists": true,
+    "require-lock-timeout": true,
+    "ban-concurrent-index-in-transaction": true,
+    "adding-not-nullable-field": true,
+    "constraint-missing-not-valid": true
+  }
 };
 function applyEnvOverrides(connection) {
   return {
@@ -81,7 +90,11 @@ function buildConfig(raw, configDir) {
     naming: { ...DEFAULT_NAMING, ...raw.naming },
     connection: applyEnvOverrides(connection),
     dump: { ...DEFAULT_DUMP, ...raw.dump },
-    lint: { ...DEFAULT_LINT, ...raw.lint }
+    lint: {
+      ...DEFAULT_LINT,
+      ...raw.lint,
+      rules: { ...DEFAULT_LINT.rules, ...raw.lint?.rules }
+    }
   };
 }
 async function loadConfig(startDir) {
@@ -1007,51 +1020,311 @@ function findConnectedComponents(newFiles, graph) {
   }
   return components;
 }
-var execFileAsync = promisify(execFile);
-async function isSquawkAvailable() {
+async function runRules(sql, rules) {
+  const violations = [];
+  let stmts;
   try {
-    await execFileAsync("squawk", ["--version"]);
-    return true;
+    const ast = await libpg.parse(sql);
+    stmts = ast.stmts;
   } catch {
-    return false;
+    return violations;
   }
+  const visitors = [];
+  for (const rule of rules) {
+    visitors.push({ ruleId: rule.id, handlers: rule.create() });
+  }
+  const createdTables = /* @__PURE__ */ new Set();
+  let lockTimeoutSet = false;
+  let inTransaction = false;
+  for (const { stmt } of stmts) {
+    const s = stmt;
+    if ("VariableSetStmt" in s) {
+      const name = s.VariableSetStmt.name;
+      if (name === "lock_timeout") lockTimeoutSet = true;
+    }
+    if ("TransactionStmt" in s) {
+      const kind = s.TransactionStmt.kind;
+      if (kind === "TRANS_STMT_BEGIN") inTransaction = true;
+      else if (kind === "TRANS_STMT_COMMIT" || kind === "TRANS_STMT_ROLLBACK") inTransaction = false;
+    }
+    if ("CreateStmt" in s) {
+      const rel = s.CreateStmt.relation;
+      if (rel?.relname) createdTables.add(rel.relname);
+    }
+    const ctx = {
+      report: null,
+      createdTables,
+      lockTimeoutSet,
+      inTransaction
+    };
+    for (const key of Object.keys(s)) {
+      const node = s[key];
+      for (const { ruleId, handlers } of visitors) {
+        const handler = handlers[key];
+        if (!handler) continue;
+        ctx.report = (v) => violations.push({ rule: ruleId, ...v });
+        handler(node, ctx);
+      }
+    }
+  }
+  return violations;
 }
-async function commandLint(config) {
-  if (!config.lint.squawk) {
-    console.log(chalk6.yellow("Squawk lint is disabled in config."));
-    return { ok: true, filesLinted: 0 };
+
+// src/rules/require-concurrent-index.ts
+var requireConcurrentIndex = {
+  id: "require-concurrent-index",
+  description: "CREATE INDEX must use CONCURRENTLY on existing tables",
+  create() {
+    return {
+      IndexStmt(node, ctx) {
+        const rel = node.relation;
+        const tableName = rel?.relname ?? "(unknown)";
+        const isNewTable = ctx.createdTables.has(tableName);
+        if (!node.concurrent && !isNewTable) {
+          ctx.report({
+            message: `CREATE INDEX on "${tableName}" without CONCURRENTLY`,
+            hint: "Use CREATE INDEX CONCURRENTLY to avoid blocking writes"
+          });
+        }
+      }
+    };
   }
-  const available = await isSquawkAvailable();
-  if (!available) {
-    throw new Error(
-      "Squawk is not installed or not in PATH. Install it: npm install -g squawk-cli  (or see https://squawkhq.com/)"
-    );
+};
+
+// src/rules/require-if-not-exists.ts
+var requireIfNotExists = {
+  id: "require-if-not-exists",
+  description: "CREATE must use IF NOT EXISTS, DROP must use IF EXISTS",
+  create() {
+    return {
+      CreateStmt(node, ctx) {
+        if (!node.if_not_exists) {
+          const rel = node.relation;
+          ctx.report({
+            message: `CREATE TABLE ${rel?.relname ?? "(unknown)"} without IF NOT EXISTS`,
+            hint: "Use CREATE TABLE IF NOT EXISTS for idempotent migrations"
+          });
+        }
+      },
+      IndexStmt(node, ctx) {
+        if (!node.if_not_exists) {
+          ctx.report({
+            message: "CREATE INDEX without IF NOT EXISTS",
+            hint: "Use CREATE INDEX ... IF NOT EXISTS for idempotent migrations"
+          });
+        }
+      },
+      DropStmt(node, ctx) {
+        if (!node.missing_ok) {
+          ctx.report({
+            message: "DROP without IF EXISTS",
+            hint: "Use DROP ... IF EXISTS for idempotent migrations"
+          });
+        }
+      }
+    };
+  }
+};
+
+// src/rules/require-lock-timeout.ts
+var requireLockTimeout = {
+  id: "require-lock-timeout",
+  description: "SET lock_timeout must appear before DDL statements",
+  create() {
+    let flagged = false;
+    function checkTimeout(ctx) {
+      if (!ctx.lockTimeoutSet && !flagged) {
+        flagged = true;
+        ctx.report({
+          message: "DDL appears before SET lock_timeout",
+          hint: "Add SET lock_timeout = '5s'; before DDL statements"
+        });
+      }
+    }
+    return {
+      CreateStmt(_node, ctx) {
+        checkTimeout(ctx);
+      },
+      IndexStmt(node, ctx) {
+        if (!node.concurrent) checkTimeout(ctx);
+      },
+      AlterTableStmt(_node, ctx) {
+        checkTimeout(ctx);
+      },
+      DropStmt(_node, ctx) {
+        checkTimeout(ctx);
+      }
+    };
   }
+};
+
+// src/rules/ban-concurrent-index-in-transaction.ts
+var banConcurrentIndexInTransaction = {
+  id: "ban-concurrent-index-in-transaction",
+  description: "CREATE INDEX CONCURRENTLY cannot run inside a transaction",
+  create() {
+    return {
+      IndexStmt(node, ctx) {
+        if (node.concurrent && ctx.inTransaction) {
+          ctx.report({
+            message: "CREATE INDEX CONCURRENTLY inside a transaction",
+            hint: "Remove BEGIN/COMMIT \u2014 CONCURRENTLY cannot run inside a transaction block"
+          });
+        }
+      }
+    };
+  }
+};
+
+// src/rules/adding-not-nullable-field.ts
+var addingNotNullableField = {
+  id: "adding-not-nullable-field",
+  description: "Adding a NOT NULL column requires a DEFAULT value",
+  create() {
+    return {
+      AlterTableStmt(node, ctx) {
+        const cmds = node.cmds;
+        if (!cmds) return;
+        for (const cmd of cmds) {
+          const alterCmd = cmd.AlterTableCmd;
+          if (!alterCmd) continue;
+          const subtype = alterCmd.subtype;
+          const isAddColumn = subtype === "AT_AddColumn" || subtype === 0;
+          if (!isAddColumn) continue;
+          const colDef = alterCmd.def;
+          if (!colDef?.ColumnDef) continue;
+          const col = colDef.ColumnDef;
+          const constraints = col.constraints;
+          if (!constraints) continue;
+          let hasNotNull = false;
+          let hasDefault = false;
+          for (const c of constraints) {
+            const constr = c.Constraint;
+            if (!constr) continue;
+            if (constr.contype === "CONSTR_NOTNULL") hasNotNull = true;
+            if (constr.contype === "CONSTR_DEFAULT") hasDefault = true;
+          }
+          if (hasNotNull && !hasDefault) {
+            const colname = col.colname;
+            ctx.report({
+              message: `Adding NOT NULL column "${colname ?? "(unknown)"}" without DEFAULT`,
+              hint: "Add a DEFAULT value or add the column as nullable first, then backfill, then set NOT NULL"
+            });
+          }
+        }
+      }
+    };
+  }
+};
+
+// src/rules/constraint-missing-not-valid.ts
+var constraintMissingNotValid = {
+  id: "constraint-missing-not-valid",
+  description: "ADD CONSTRAINT should use NOT VALID to avoid full table scan",
+  create() {
+    return {
+      AlterTableStmt(node, ctx) {
+        const cmds = node.cmds;
+        if (!cmds) return;
+        for (const cmd of cmds) {
+          const alterCmd = cmd.AlterTableCmd;
+          if (!alterCmd) continue;
+          const subtype = alterCmd.subtype;
+          const isAddConstraint = subtype === "AT_AddConstraint" || subtype === 14;
+          if (!isAddConstraint) continue;
+          const def = alterCmd.def;
+          if (!def?.Constraint) continue;
+          const constr = def.Constraint;
+          const contype = constr.contype;
+          const needsNotValid = contype === "CONSTR_FOREIGN" || contype === "CONSTR_CHECK";
+          if (!needsNotValid) continue;
+          if (!constr.skip_validation) {
+            const conname = constr.conname;
+            ctx.report({
+              message: `ADD CONSTRAINT ${conname ? `"${conname}" ` : ""}without NOT VALID`,
+              hint: "Use NOT VALID to avoid a full table scan that blocks writes, then VALIDATE CONSTRAINT separately"
+            });
+          }
+        }
+      }
+    };
+  }
+};
+
+// src/rules/index.ts
+var ALL_RULES = [
+  requireConcurrentIndex,
+  requireIfNotExists,
+  requireLockTimeout,
+  banConcurrentIndexInTransaction,
+  addingNotNullableField,
+  constraintMissingNotValid
+];
+
+// src/commands/lint.ts
+async function loadCustomRules(config) {
+  const dir = config.lint.customRulesDir;
+  if (!dir) return [];
+  const absDir = resolveFromConfig(config, dir);
+  let entries;
+  try {
+    entries = await readdir(absDir);
+  } catch {
+    return [];
+  }
+  const rules = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".js") && !entry.endsWith(".mjs")) continue;
+    const filePath = resolve(absDir, entry);
+    try {
+      const mod = await import(pathToFileURL(filePath).href);
+      const rule = mod.default ?? mod;
+      if (rule && typeof rule.id === "string" && typeof rule.create === "function") {
+        rules.push(rule);
+      }
+    } catch (err) {
+      console.error(chalk6.yellow(`Warning: failed to load custom rule from ${entry}: ${err.message}`));
+    }
+  }
+  return rules;
+}
+async function commandLint(config) {
   const files = await scanMigrations(config);
   if (files.length === 0) {
     console.log(chalk6.yellow("No migration files to lint."));
-    return { ok: true, filesLinted: 0 };
+    return { ok: true, filesLinted: 0, violations: 0 };
+  }
+  const customRules = await loadCustomRules(config);
+  const allRules = [...ALL_RULES, ...customRules];
+  const enabledRules = allRules.filter((r) => config.lint.rules[r.id] !== false);
+  if (enabledRules.length === 0) {
+    console.log(chalk6.yellow("All lint rules are disabled."));
+    return { ok: true, filesLinted: files.length, violations: 0 };
   }
-  let hasErrors = false;
+  let totalViolations = 0;
   for (const f of files) {
-    try {
-      await execFileAsync("squawk", [f.filePath]);
-    } catch (err) {
-      hasErrors = true;
-      const execErr = err;
-      console.error(chalk6.red(`
-\u2717 ${f.fileName}:`));
-      if (execErr.stdout) console.error(execErr.stdout);
-      if (execErr.stderr) console.error(execErr.stderr);
+    const sql = await readFile(f.filePath, "utf-8");
+    const violations = await runRules(sql, enabledRules);
+    if (violations.length > 0) {
+      totalViolations += violations.length;
+      printViolations(f.fileName, violations);
     }
   }
-  if (hasErrors) {
+  if (totalViolations > 0) {
     console.error(chalk6.red(`
-Lint failed.`));
+Lint failed: ${totalViolations} violation(s).`));
   } else {
     console.log(chalk6.green(`\u2713 ${files.length} file(s) passed lint.`));
   }
-  return { ok: !hasErrors, filesLinted: files.length };
+  return { ok: totalViolations === 0, filesLinted: files.length, violations: totalViolations };
+}
+function printViolations(fileName, violations) {
+  console.error(chalk6.red(`
+\u2717 ${fileName}:`));
+  for (const v of violations) {
+    console.error(chalk6.red(`  [${v.rule}] ${v.message}`));
+    console.error(chalk6.gray(`    hint: ${v.hint}`));
+  }
 }
 var { Client } = pg;
 var ADVISORY_LOCK_KEY = "migraguard-apply";
@@ -1228,7 +1501,7 @@ async function commandEditable(config) {
   }
   return { editableFiles, entries };
 }
-var execFileAsync2 = promisify(execFile);
+var execFileAsync = promisify(execFile);
 function buildPsqlEnv(config) {
   const env = { ...process.env };
   env["PGHOST"] = config.connection.host;
@@ -1243,7 +1516,7 @@ function buildPsqlEnv(config) {
 async function executePsqlFile(config, filePath) {
   const env = buildPsqlEnv(config);
   try {
-    const { stdout, stderr } = await execFileAsync2(
+    const { stdout, stderr } = await execFileAsync(
       "psql",
       ["-v", "ON_ERROR_STOP=1", "-f", filePath],
       { env }
@@ -1258,7 +1531,7 @@ async function executePsqlFile(config, filePath) {
     };
   }
 }
-var execFileAsync3 = promisify(execFile);
+var execFileAsync2 = promisify(execFile);
 function buildPgDumpEnv(config) {
   const env = { ...process.env };
   env["PGHOST"] = config.connection.host;
@@ -1278,11 +1551,11 @@ async function dumpSchema(config) {
   let stdout;
   if (pgDumpCmd && pgDumpCmd.length > 0) {
     const [cmd, ...baseArgs] = pgDumpCmd;
-    const { stdout: out } = await execFileAsync3(cmd, [...baseArgs, ...dumpArgs]);
+    const { stdout: out } = await execFileAsync2(cmd, [...baseArgs, ...dumpArgs]);
     stdout = out;
   } else {
     const env = buildPgDumpEnv(config);
-    const { stdout: out } = await execFileAsync3("pg_dump", dumpArgs, { env });
+    const { stdout: out } = await execFileAsync2("pg_dump", dumpArgs, { env });
     stdout = out;
   }
   if (config.dump.normalize) {
@@ -1682,7 +1955,7 @@ async function commandDiff(config) {
   return { identical: false, diff };
 }
 var { Client: Client2 } = pg;
-var execFileAsync4 = promisify(execFile);
+var execFileAsync3 = promisify(execFile);
 function shadowDbName() {
   const suffix = randomBytes(4).toString("hex");
   return `migraguard_shadow_${suffix}`;
@@ -1732,11 +2005,11 @@ async function dumpSourceToShadow(config, shadowName) {
   let dumpOutput;
   if (pgDumpCmd && pgDumpCmd.length > 0) {
     const [cmd, ...baseArgs] = pgDumpCmd;
-    const { stdout } = await execFileAsync4(cmd, [...baseArgs, "--no-owner", "--no-privileges"]);
+    const { stdout } = await execFileAsync3(cmd, [...baseArgs, "--no-owner", "--no-privileges"]);
     dumpOutput = stdout;
   } else {
     env["PGDATABASE"] = conn.database;
-    const { stdout } = await execFileAsync4("pg_dump", ["--no-owner", "--no-privileges"], { env });
+    const { stdout } = await execFileAsync3("pg_dump", ["--no-owner", "--no-privileges"], { env });
     dumpOutput = stdout;
   }
   const tmpFile = join(tmpdir(), `migraguard-dump-${randomBytes(4).toString("hex")}.sql`);
@@ -1744,7 +2017,7 @@ async function dumpSourceToShadow(config, shadowName) {
   try {
     const restoreEnv = buildEnv(conn);
     restoreEnv["PGDATABASE"] = shadowName;
-    await execFileAsync4("psql", ["-v", "ON_ERROR_STOP=1", "-f", tmpFile], {
+    await execFileAsync3("psql", ["-v", "ON_ERROR_STOP=1", "-f", tmpFile], {
       env: restoreEnv,
       maxBuffer: 50 * 1024 * 1024
     });
@@ -2202,7 +2475,7 @@ program.command("squash").description("Squash multiple new migration files into
   const config = await loadConfig();
   await commandSquash(config);
 }));
-program.command("lint").description("Run Squawk lint on migration files").action(() => run(async () => {
+program.command("lint").description("Run built-in safety rules on migration files").action(() => run(async () => {
   const config = await loadConfig();
   const result = await commandLint(config);
   if (!result.ok) process.exit(1);