ddlforge 0.1.0

package/dist/src/rules/unbatchedBackfill.js

@@ -0,0 +1,58 @@
+/**
+ * ddlforge Rule: Unbatched DML in Migration (Bare UPDATE/DELETE)
+ *
+ * Severity: WARNING
+ * Lock: ROW EXCLUSIVE
+ */
+import { PostgresLockLevel } from '../engine/locks.js';
+export const unbatchedBackfillRule = {
+    id: 'unbatched-dml',
+    name: 'Unbatched DML in Migration',
+    description: 'Bare UPDATE and DELETE statements in migrations can lock millions of rows, bloat WAL, and block autovacuum.',
+    defaultSeverity: 'WARNING',
+    lockLevel: PostgresLockLevel.ROW_EXCLUSIVE,
+    check(context) {
+        const findings = [];
+        for (const stmt of context.statements) {
+            if (stmt.hasIgnore(this.id))
+                continue;
+            const tokens = stmt.tokens;
+            if (tokens.length < 2)
+                continue;
+            const firstVal = tokens[0].value;
+            const isUpdate = firstVal === 'UPDATE';
+            const isDelete = firstVal === 'DELETE' && tokens[1]?.value === 'FROM';
+            if (!isUpdate && !isDelete)
+                continue;
+            // Check for batching comments: -- batch, -- batched, -- batch-size
+            const hasBatchComment = stmt.comments.some(c => /batch/i.test(c));
+            if (hasBatchComment)
+                continue;
+            // Check if statement contains LIMIT inside a subquery
+            const hasLimit = tokens.some(t => t.value === 'LIMIT');
+            if (hasLimit)
+                continue;
+            // Check if WHERE clause exists
+            const hasWhere = tokens.some(t => t.value === 'WHERE');
+            const opName = isUpdate ? 'UPDATE' : 'DELETE';
+            const tableName = isUpdate ? (tokens[1]?.raw ?? 'table') : (tokens[2]?.raw ?? 'table');
+            findings.push({
+                ruleId: this.id,
+                ruleName: this.name,
+                severity: !hasWhere ? 'BLOCKER' : this.defaultSeverity,
+                lockLevel: this.lockLevel,
+                message: `Bare ${opName} statement on table "${tableName}" without batching or LIMIT.`,
+                detail: `Unbatched ${opName} statements in migrations hold ROW EXCLUSIVE locks on affected rows for the duration of the migration transaction, ` +
+                    'generating massive WAL volume and risking transaction timeouts.',
+                suggestion: 'Migrate large backfills out-of-band using asynchronous background jobs in small batches (1,000–5,000 rows). ' +
+                    'If this operation targets a small static/lookup table, add `-- ddlforge-ignore unbatched-dml`.',
+                file: context.filePath,
+                line: stmt.startLine,
+                column: stmt.startColumn,
+                codeSnippet: stmt.raw,
+            });
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=unbatchedBackfill.js.map

package/dist/src/rules/unbatchedBackfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unbatchedBackfill.js","sourceRoot":"","sources":["../../../src/rules/unbatchedBackfill.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,CAAC,MAAM,qBAAqB,GAAS;IACzC,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,4BAA4B;IAClC,WAAW,EAAE,6GAA6G;IAC1H,eAAe,EAAE,SAAS;IAC1B,SAAS,EAAE,iBAAiB,CAAC,aAAa;IAE1C,KAAK,CAAC,OAAoB;QACxB,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YAEtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAC3B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAEhC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACjC,MAAM,QAAQ,GAAG,QAAQ,KAAK,QAAQ,CAAC;YACvC,MAAM,QAAQ,GAAG,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,MAAM,CAAC;YAEtE,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAErC,mEAAmE;YACnE,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAClE,IAAI,eAAe;gBAAE,SAAS;YAE9B,sDAAsD;YACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC;YACvD,IAAI,QAAQ;gBAAE,SAAS;YAEvB,+BAA+B;YAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC;YACvD,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;YAE9C,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;YAEvF,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe;gBACtD,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,OAAO,EAAE,QAAQ,MAAM,wBAAwB,SAAS,8BAA8B;gBACtF,MAAM,EACJ,aAAa,MAAM,qHAAqH;oBACxI,iEAAiE;gBACnE,UAAU,EACR,8GAA8G;oBAC9G,gGAAgG;gBAClG,IAAI,EAAE,OAAO,CAAC,QAAQ;gBACtB,IAAI,EAAE,IAAI,CAAC,SAAS;gBACpB,MAAM,EAAE,IAAI,CAAC,WAAW;gBACxB,WAAW,EAAE,IAAI,CAAC,GAAG;aACtB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ddlforge",
+  "version": "0.1.0",
+  "description": "Ultra-fast, zero-runtime-dependency Postgres migration lock linter and data-loss prevention engine CLI in Node.js 20+ and TypeScript",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "ddlforge": "dist/bin/ddlforge.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"const fs=require('fs'); try{fs.chmodSync('dist/bin/ddlforge.js', 0o755)}catch{}\"",
+    "test:build": "tsc -p tsconfig.test.json",
+    "test": "npm run test:build && node --test dist/test/analyzer.test.js",
+    "test:watch": "node --test --watch dist/test/analyzer.test.js",
+    "prepack": "node -e \"const fs=require('fs'); try{fs.rmSync('dist/test', {recursive:true, force:true})}catch{}\"",
+    "prepublishOnly": "npm run build && node -e \"const fs=require('fs'); try{fs.rmSync('dist/test', {recursive:true, force:true})}catch{}\""
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "migration",
+    "ddl",
+    "lock",
+    "linter",
+    "prisma",
+    "drizzle",
+    "zero-downtime"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  }
+}