@rehearsal-db/core 1.1.0 → 1.3.0

package/dist/src/runtime/migration_insights_input.mjs

@@ -0,0 +1,153 @@
+/** Exact, bounded project-local SQL input. Contents never enter public findings. */
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, open, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readMigrationFileInventory } from "./migration_history.mjs";
+import { RehearsalError } from "../shared/diagnostics.mjs";
+import { holdPathAncestry, } from "../shared/held_path_ancestry.mjs";
+export const MIGRATION_INSIGHTS_LIMITS = Object.freeze({
+    maximumFiles: 10000,
+    maximumDirectoryEntries: 10000,
+    maximumCandidates: 1000,
+    maximumFileBytes: 2 * 1024 * 1024,
+    maximumTotalBytes: 16 * 1024 * 1024,
+    maximumFindings: 5000,
+});
+const inside = (root, path) => {
+    const value = relative(root, path);
+    return !value.startsWith("..") && !isAbsolute(value);
+};
+const inputError = () => new RehearsalError({
+    category: "configuration_invalid",
+    code: "CONFIGURATION_INVALID",
+    message: "Migration Insights requires bounded, unchanged regular SQL files inside the project; symlinks and unsafe filenames are refused.",
+    refused: "No SQL was executed and no database or engine was contacted.",
+    suggestions: [
+        "Review project-local migration files and the documented Insights input limits, then request a fresh inspection.",
+    ],
+});
+export const createMigrationInsightsInput = (projectRoot) => {
+    const contents = new Map();
+    let totalBytes = 0;
+    let totalFiles = 0;
+    const readInventory = async (directory) => {
+        let ancestry;
+        try {
+            const lexicalRoot = resolve(projectRoot);
+            const lexicalDirectory = resolve(fileURLToPath(directory));
+            if (!inside(lexicalRoot, lexicalDirectory))
+                throw inputError();
+            const root = await realpath(lexicalRoot);
+            const canonicalDirectory = await realpath(lexicalDirectory);
+            if (canonicalDirectory !==
+                resolve(root, relative(lexicalRoot, lexicalDirectory)))
+                throw inputError();
+            const held = await holdPathAncestry(canonicalDirectory);
+            ancestry = held;
+            await held.assertUnchanged();
+            const parentBefore = await lstat(canonicalDirectory);
+            if (!parentBefore.isDirectory() || parentBefore.isSymbolicLink())
+                throw inputError();
+            const inventory = await readMigrationFileInventory(pathToFileURL(`${held.path}${sep}`), {
+                maximumFiles: MIGRATION_INSIGHTS_LIMITS.maximumFiles,
+                maximumDirectoryEntries: MIGRATION_INSIGHTS_LIMITS.maximumDirectoryEntries,
+                readBytes: async (url, filename) => {
+                    if (++totalFiles > MIGRATION_INSIGHTS_LIMITS.maximumFiles ||
+                        Buffer.byteLength(filename) > 255 ||
+                        /[\\/%:#?\u0000-\u001f\u007f-\u009f\u2028\u2029\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(filename))
+                        throw inputError();
+                    const suppliedPath = fileURLToPath(url);
+                    if (suppliedPath !== join(held.path, filename) ||
+                        basename(suppliedPath) !== filename)
+                        throw inputError();
+                    // Read through the canonical directory, never a caller's root alias.
+                    const path = join(canonicalDirectory, filename);
+                    try {
+                        await held.assertUnchanged();
+                        const leafBefore = await lstat(path);
+                        if (!leafBefore.isFile() || leafBefore.isSymbolicLink())
+                            throw inputError();
+                        const handle = await open(path, constants.O_RDONLY |
+                            constants.O_NOFOLLOW |
+                            constants.O_NONBLOCK);
+                        try {
+                            const before = await handle.stat();
+                            if (!before.isFile() ||
+                                before.dev !== leafBefore.dev ||
+                                before.ino !== leafBefore.ino ||
+                                before.size > MIGRATION_INSIGHTS_LIMITS.maximumFileBytes ||
+                                totalBytes + before.size >
+                                    MIGRATION_INSIGHTS_LIMITS.maximumTotalBytes)
+                                throw inputError();
+                            const buffer = Buffer.alloc(before.size + 1);
+                            let offset = 0;
+                            while (offset < buffer.length) {
+                                const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+                                if (!bytesRead)
+                                    break;
+                                offset += bytesRead;
+                            }
+                            const after = await handle.stat();
+                            const leafAfter = await lstat(path);
+                            const parentAfter = await lstat(canonicalDirectory);
+                            if (offset !== before.size ||
+                                before.dev !== after.dev ||
+                                before.ino !== after.ino ||
+                                before.size !== after.size ||
+                                before.mtimeMs !== after.mtimeMs ||
+                                before.ctimeMs !== after.ctimeMs ||
+                                !leafAfter.isFile() ||
+                                leafAfter.isSymbolicLink() ||
+                                before.dev !== leafAfter.dev ||
+                                before.ino !== leafAfter.ino ||
+                                before.ctimeMs !== leafAfter.ctimeMs ||
+                                parentAfter.isSymbolicLink() ||
+                                parentBefore.dev !== parentAfter.dev ||
+                                parentBefore.ino !== parentAfter.ino ||
+                                (await realpath(dirname(path))) !== canonicalDirectory)
+                                throw inputError();
+                            await held.assertUnchanged();
+                            const bytes = buffer.subarray(0, offset);
+                            const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+                            const sha256 = createHash("sha256").update(bytes).digest("hex");
+                            const prior = contents.get(path);
+                            if (prior && prior.sha256 !== sha256)
+                                throw inputError();
+                            totalBytes += offset;
+                            contents.set(path, { sha256, text });
+                            return bytes;
+                        }
+                        finally {
+                            await handle.close();
+                        }
+                    }
+                    catch {
+                        throw inputError();
+                    }
+                },
+            });
+            await held.assertUnchanged();
+            return inventory;
+        }
+        catch {
+            throw inputError();
+        }
+        finally {
+            try {
+                await ancestry?.close();
+            }
+            catch {
+                throw inputError();
+            }
+        }
+    };
+    return {
+        readInventory,
+        sourceFor: (path, sha256) => {
+            const retained = contents.get(resolve(path));
+            return retained?.sha256 === sha256 ? retained.text : undefined;
+        },
+    };
+};

package/dist/src/runtime/migration_sql_lexer.d.mts

@@ -0,0 +1,14 @@
+/** Bounded PostgreSQL lexical input, not a SQL parser or validator. */
+export type ScanUnknownReason = "unsupported_sql" | "malformed_sql" | "input_limit";
+export interface SqlToken {
+    kind: "word" | "identifier" | "literal" | "symbol";
+    value: string;
+    line: number;
+    column: number;
+    depth: number;
+}
+export declare const lexMigrationSql: (source: string) => {
+    tokens: SqlToken[];
+    unknownReasons: ScanUnknownReason[];
+    ambiguousQuotes: boolean;
+};

package/dist/src/runtime/migration_sql_lexer.mjs

@@ -0,0 +1,204 @@
+const maxBytes = 2 * 1024 * 1024;
+const maxTokens = 20_000;
+const maxDepth = 128;
+const wordStart = (character) => /[A-Za-z_]/u.test(character) || character.charCodeAt(0) >= 128;
+const wordPart = (character) => wordStart(character) || /[0-9$]/u.test(character);
+export const lexMigrationSql = (source) => {
+    const tokens = [];
+    const reasons = new Set();
+    if (Buffer.byteLength(source, "utf8") > maxBytes)
+        return { tokens, unknownReasons: ["input_limit"], ambiguousQuotes: false };
+    if (source.includes("\0"))
+        reasons.add("malformed_sql");
+    let ambiguousQuotes = false;
+    let offset = 0;
+    let line = 1;
+    let column = 1;
+    const groups = [];
+    const advance = (end) => {
+        while (offset < end) {
+            const character = source[offset++];
+            if (character === "\r") {
+                if (source[offset] === "\n" && offset < end)
+                    offset += 1;
+                line += 1;
+                column = 1;
+            }
+            else if (character === "\n") {
+                line += 1;
+                column = 1;
+            }
+            else
+                column += 1;
+        }
+    };
+    const emit = (kind, value, end, depth = groups.length) => {
+        if (tokens.length >= maxTokens) {
+            reasons.add("input_limit");
+            return false;
+        }
+        tokens.push({ kind, value, line, column, depth });
+        advance(end);
+        return true;
+    };
+    const quoted = (start, quote, escapes) => {
+        let cursor = start + 1;
+        while (cursor < source.length) {
+            if (source[cursor] === "\0")
+                reasons.add("malformed_sql");
+            if (source[cursor] === "\\") {
+                // Plain strings depend on standard_conforming_strings, which is not read.
+                if (quote === "'" && !escapes) {
+                    reasons.add("unsupported_sql");
+                    ambiguousQuotes = true;
+                }
+                if (escapes) {
+                    cursor += 2;
+                    continue;
+                }
+            }
+            if (source[cursor] === quote) {
+                if (source[cursor + 1] === quote)
+                    cursor += 2;
+                else
+                    return cursor + 1;
+            }
+            else
+                cursor += 1;
+        }
+        reasons.add("malformed_sql");
+        return source.length;
+    };
+    while (offset < source.length) {
+        const character = source[offset];
+        if (/[ \t\n\r\f\v]/u.test(character)) {
+            // Consume CRLF together so editor positions count a single newline.
+            advance(offset + (character === "\r" && source[offset + 1] === "\n" ? 2 : 1));
+            continue;
+        }
+        if (source.startsWith("--", offset)) {
+            let end = offset + 2;
+            while (end < source.length && !/[\r\n]/u.test(source[end]))
+                end += 1;
+            advance(end);
+            continue;
+        }
+        if (source.startsWith("/*", offset)) {
+            let nested = 1;
+            let cursor = offset + 2;
+            while (cursor < source.length && nested > 0) {
+                if (source.startsWith("/*", cursor)) {
+                    nested += 1;
+                    cursor += 2;
+                    if (nested > maxDepth)
+                        break;
+                }
+                else if (source.startsWith("*/", cursor)) {
+                    nested -= 1;
+                    cursor += 2;
+                }
+                else
+                    cursor += 1;
+            }
+            if (nested > maxDepth) {
+                reasons.add("input_limit");
+                break;
+            }
+            if (nested > 0)
+                reasons.add("malformed_sql");
+            advance(cursor);
+            continue;
+        }
+        if (source.startsWith("*/", offset) || character === "\0") {
+            reasons.add("malformed_sql");
+            break;
+        }
+        if ((character === "E" || character === "e") &&
+            source[offset + 1] === "'") {
+            if (!emit("literal", "", quoted(offset + 1, "'", true)))
+                break;
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            const end = quoted(offset, character, false);
+            if (character === '"' && end === offset + 2)
+                reasons.add("malformed_sql");
+            if (!emit(character === "'" ? "literal" : "identifier", "", end))
+                break;
+            continue;
+        }
+        if (character === "$") {
+            let tagEnd = offset + 1;
+            if (wordStart(source[tagEnd] ?? "")) {
+                tagEnd += 1;
+                while (tagEnd < source.length &&
+                    (wordStart(source[tagEnd]) || /[0-9]/u.test(source[tagEnd])))
+                    tagEnd += 1;
+            }
+            if (source[tagEnd] === "$") {
+                const delimiter = source.slice(offset, tagEnd + 1);
+                const close = source.indexOf(delimiter, tagEnd + 1);
+                if (close < 0)
+                    reasons.add("malformed_sql");
+                if (!emit("literal", "", close < 0 ? source.length : close + delimiter.length))
+                    break;
+                continue;
+            }
+            let parameterEnd = offset + 1;
+            while (/[0-9]/u.test(source[parameterEnd] ?? ""))
+                parameterEnd += 1;
+            if (parameterEnd > offset + 1) {
+                if (!emit("literal", "", parameterEnd))
+                    break;
+                continue;
+            }
+            reasons.add("unsupported_sql");
+        }
+        if (wordStart(character)) {
+            let end = offset + 1;
+            while (end < source.length && wordPart(source[end]))
+                end += 1;
+            if (!emit("word", source.slice(offset, end).toUpperCase(), end))
+                break;
+            continue;
+        }
+        if (/[0-9]/u.test(character)) {
+            let end = offset + 1;
+            while (end < source.length && /[0-9A-Za-z_.]/u.test(source[end]))
+                end += 1;
+            if (!emit("literal", "", end))
+                break;
+            continue;
+        }
+        if (character === "(" || character === "[") {
+            if (groups.length >= maxDepth) {
+                reasons.add("input_limit");
+                break;
+            }
+            if (!emit("symbol", character, offset + 1))
+                break;
+            groups.push(character);
+        }
+        else if (character === ")" || character === "]") {
+            if (groups.pop() !== (character === ")" ? "(" : "[")) {
+                reasons.add("malformed_sql");
+                break;
+            }
+            if (!emit("symbol", character, offset + 1))
+                break;
+        }
+        else {
+            if (character === ";" && groups.length > 0)
+                reasons.add("malformed_sql");
+            if (character === "\\" ||
+                character === "`" ||
+                character.charCodeAt(0) < 32)
+                reasons.add("unsupported_sql");
+            if (!emit("symbol", character, offset + 1))
+                break;
+        }
+    }
+    if (groups.length > 0)
+        reasons.add("malformed_sql");
+    return { tokens, unknownReasons: [...reasons], ambiguousQuotes };
+};

package/dist/src/runtime/migration_sql_scan.d.mts

@@ -0,0 +1,16 @@
+import { type ScanUnknownReason } from "./migration_sql_lexer.mjs";
+export type MigrationSqlRule = "drop_table" | "drop_column" | "truncate" | "broad_update" | "broad_delete" | "not_null" | "new_constraint" | "cascade";
+export interface MigrationSqlFinding {
+    rule: MigrationSqlRule;
+    severity: "warning" | "danger";
+    line: number;
+    column: number;
+}
+export interface MigrationSqlScan {
+    /** Complete bounded lexical/rule coverage, never SQL validity or a safe verdict. */
+    complete: boolean;
+    findings: MigrationSqlFinding[];
+    unknownReasons: ScanUnknownReason[];
+}
+/** Static, local-only review hints. Never executes SQL or returns input text. */
+export declare const scanMigrationSql: (source: string) => MigrationSqlScan;