@rehearsal-db/core 1.0.2 → 1.2.0

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

@@ -0,0 +1,137 @@
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+export declare const MIGRATION_INSIGHT_RULES: Readonly<{
+    drop_table: {
+        summary: string;
+        suggestion: string;
+    };
+    drop_column: {
+        summary: string;
+        suggestion: string;
+    };
+    truncate: {
+        summary: string;
+        suggestion: string;
+    };
+    broad_update: {
+        summary: string;
+        suggestion: string;
+    };
+    broad_delete: {
+        summary: string;
+        suggestion: string;
+    };
+    not_null: {
+        summary: string;
+        suggestion: string;
+    };
+    new_constraint: {
+        summary: string;
+        suggestion: string;
+    };
+    cascade: {
+        summary: string;
+        suggestion: string;
+    };
+}>;
+type Verdict = "static_warnings" | "no_detected_warning" | "unknown";
+export declare const inspectMigrationInsights: (options?: RehearsalConfigPathOptions) => Promise<{
+    schemaVersion: 1;
+    inspectorVersion: string;
+    candidateSha256: string;
+    candidateCount: number;
+    verdict: Verdict;
+    summary: {
+        findingCount: number;
+        unknownCount: number;
+    };
+    targets: {
+        name: string;
+        provider: "postgresql" | "supabase";
+        baselineGenerationId: string;
+        candidateSha256: string;
+        entries: {
+            version: string;
+            filename: string;
+            sha256: string;
+            workspaceRelativePath: string | null;
+            verdict: Verdict;
+            coverage: "incomplete" | "recognized_lexical_rules";
+            unknownReasons: import("./migration_sql_lexer.mjs").ScanUnknownReason[];
+            findings: ({
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            } | {
+                rule: import("./migration_sql_scan.mjs").MigrationSqlRule;
+                severity: "warning" | "danger";
+                line: number;
+                column: number;
+                summary: string;
+                suggestion: string;
+            })[];
+        }[];
+    }[];
+    limits: Readonly<{
+        maximumFiles: 10000;
+        maximumDirectoryEntries: 10000;
+        maximumCandidates: 1000;
+        maximumFileBytes: number;
+        maximumTotalBytes: number;
+        maximumFindings: 5000;
+    }>;
+    safety: {
+        readsSqlBodies: boolean;
+        executesSql: boolean;
+        startsEngine: boolean;
+        contactsDatabase: boolean;
+        includesSqlOrRowValues: boolean;
+    };
+    limitation: string;
+}>;
+export declare const renderMigrationInsights: (report: Awaited<ReturnType<typeof inspectMigrationInsights>>) => string;
+export {};

package/dist/src/runtime/migration_insights.mjs

@@ -0,0 +1,143 @@
+/** Static warnings bound to the existing complete candidate plan, never a safety proof. */
+import { join, relative, resolve, sep } from "node:path";
+import { realpath } from "node:fs/promises";
+import { REHEARSAL_VERSION, RehearsalError } from "../shared/diagnostics.mjs";
+import { isMigrationWorkspacePath } from "./migration_failure_source.mjs";
+import { createMigrationInsightsInput, MIGRATION_INSIGHTS_LIMITS, } from "./migration_insights_input.mjs";
+import { scanMigrationSql } from "./migration_sql_scan.mjs";
+import { inspectRehearsalMigrations } from "./plan.mjs";
+import { inspectRuntimeTopologyCandidates } from "./topology.mjs";
+export const MIGRATION_INSIGHT_RULES = Object.freeze({
+    drop_table: {
+        summary: "A table may be removed.",
+        suggestion: "Review dependent objects and preserve any required rows before dropping the table.",
+    },
+    drop_column: {
+        summary: "A column and its stored values may be removed.",
+        suggestion: "Review populated values and dependent application code before dropping the column.",
+    },
+    truncate: {
+        summary: "All rows in the selected table may be removed.",
+        suggestion: "Confirm the intended data loss and review identity, foreign-key and cascade behavior.",
+    },
+    broad_update: {
+        summary: "An UPDATE has no top-level WHERE clause.",
+        suggestion: "Review the intended row scope; a nested WHERE does not restrict the outer UPDATE.",
+    },
+    broad_delete: {
+        summary: "A DELETE has no top-level WHERE clause.",
+        suggestion: "Review the intended row scope; a nested WHERE does not restrict the outer DELETE.",
+    },
+    not_null: {
+        summary: "A NOT NULL requirement may reject existing rows.",
+        suggestion: "Check existing NULL values and apply a reviewed backfill before enforcing the requirement.",
+    },
+    new_constraint: {
+        summary: "A new constraint may reject existing rows.",
+        suggestion: "Check NULL, duplicate, orphan and CHECK violations as appropriate; SQL text alone cannot establish compliance.",
+    },
+    cascade: {
+        summary: "CASCADE can affect dependent objects or rows.",
+        suggestion: "Review the dependency graph; this static warning does not measure the cascade's actual reach.",
+    },
+});
+const verdict = (complete, warnings) => !complete ? "unknown" : warnings ? "static_warnings" : "no_detected_warning";
+const inspectionError = (message) => new RehearsalError({
+    category: "configuration_invalid",
+    code: "CONFIGURATION_INVALID",
+    message,
+    refused: "No SQL was executed and no database or engine was contacted.",
+    suggestions: [
+        "Review the documented input limits and request a fresh complete migration inspection.",
+    ],
+});
+export const inspectMigrationInsights = async (options = {}) => {
+    const projectRoot = await realpath(resolve(options.projectRoot ?? process.cwd()));
+    const input = createMigrationInsightsInput(projectRoot);
+    const candidates = await inspectRuntimeTopologyCandidates({ ...options, projectRoot }, (selected) => inspectRehearsalMigrations(selected, input.readInventory));
+    if (candidates.candidateCount > MIGRATION_INSIGHTS_LIMITS.maximumCandidates)
+        throw inspectionError("Migration Insights exceeds its bounded 1,000-candidate plan.");
+    let findingCount = 0;
+    let unknownCount = 0;
+    const targets = candidates.targets.map((target) => {
+        const entries = target.summary.candidates.map((candidate) => {
+            const path = join(target.paths.migrationDirectory, candidate.filename);
+            const source = input.sourceFor(path, candidate.sha256);
+            if (source === undefined)
+                throw inspectionError("Migration Insights could not retain its exact reviewed input. Refresh the plan.");
+            const scan = scanMigrationSql(source);
+            const remaining = MIGRATION_INSIGHTS_LIMITS.maximumFindings - findingCount;
+            const limited = scan.findings.length > remaining;
+            const findings = scan.findings
+                .slice(0, Math.max(0, remaining))
+                .map((finding) => ({
+                ...finding,
+                ...MIGRATION_INSIGHT_RULES[finding.rule],
+            }));
+            findingCount += findings.length;
+            const complete = scan.complete && !limited;
+            if (!complete)
+                unknownCount++;
+            const workspacePath = relative(projectRoot, path).split(sep).join("/");
+            return {
+                version: candidate.version,
+                filename: candidate.filename,
+                sha256: candidate.sha256,
+                workspaceRelativePath: isMigrationWorkspacePath(workspacePath)
+                    ? workspacePath
+                    : null,
+                verdict: verdict(complete, findings.length),
+                coverage: complete
+                    ? "recognized_lexical_rules"
+                    : "incomplete",
+                unknownReasons: [
+                    ...new Set([
+                        ...scan.unknownReasons,
+                        ...(limited ? ["input_limit"] : []),
+                    ]),
+                ],
+                findings,
+            };
+        });
+        return {
+            name: target.name,
+            provider: target.config.runtime.target,
+            baselineGenerationId: target.summary.baselineGenerationId,
+            candidateSha256: target.summary.candidateSha256,
+            entries,
+        };
+    });
+    return {
+        schemaVersion: 1,
+        inspectorVersion: REHEARSAL_VERSION,
+        candidateSha256: candidates.candidateSha256,
+        candidateCount: candidates.candidateCount,
+        verdict: verdict(unknownCount === 0, findingCount),
+        summary: { findingCount, unknownCount },
+        targets,
+        limits: MIGRATION_INSIGHTS_LIMITS,
+        safety: {
+            readsSqlBodies: true,
+            executesSql: false,
+            startsEngine: false,
+            contactsDatabase: false,
+            includesSqlOrRowValues: false,
+        },
+        limitation: "Static lexical warnings only. No detected warning is not a safety or syntax-validity verdict; data impact, permissions, locks and production behavior are not measured.",
+    };
+};
+export const renderMigrationInsights = (report) => [
+    "MIGRATION INSIGHTS — STATIC, READ ONLY",
+    `${report.candidateCount} pending candidates · ${report.summary.findingCount} warnings · ${report.summary.unknownCount} incomplete analyses`,
+    `Exact candidate digest: ${report.candidateSha256}`,
+    ...report.targets.flatMap((target) => target.entries.flatMap((entry) => [
+        `${target.name}/${entry.filename}: ${entry.verdict.replaceAll("_", " ")}`,
+        ...entry.findings.map((finding) => `  ${finding.line}:${finding.column} ${finding.rule}: ${finding.summary} ${finding.suggestion}`),
+        ...(entry.unknownReasons.length
+            ? [
+                "  Unsupported, malformed or bounded input remains unknown; review this file manually.",
+            ]
+            : []),
+    ])),
+    report.limitation,
+].join("\n");

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

@@ -0,0 +1,13 @@
+import { readMigrationFileInventory } from "./migration_history.mjs";
+export declare const MIGRATION_INSIGHTS_LIMITS: Readonly<{
+    maximumFiles: 10000;
+    maximumDirectoryEntries: 10000;
+    maximumCandidates: 1000;
+    maximumFileBytes: number;
+    maximumTotalBytes: number;
+    maximumFindings: 5000;
+}>;
+export declare const createMigrationInsightsInput: (projectRoot: string) => {
+    readInventory: typeof readMigrationFileInventory;
+    sourceFor: (path: string, sha256: string) => string | undefined;
+};

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;