@rehearsal-db/core 1.1.0 → 1.2.0

package/dist/src/runtime/migration_sql_scan.mjs

@@ -0,0 +1,369 @@
+import { lexMigrationSql, } from "./migration_sql_lexer.mjs";
+const word = (token, value) => token?.kind === "word" && token.value === value;
+const name = (token) => token?.kind === "word" || token?.kind === "identifier";
+const qualifiedNameEnd = (tokens, start) => {
+    if (!name(tokens[start]))
+        return start;
+    let end = start + 1;
+    while (tokens[end]?.value === "." && name(tokens[end + 1]))
+        end += 2;
+    return end;
+};
+const topTokens = (tokens, depth) => tokens.filter((token) => token.depth === depth);
+/** Static, local-only review hints. Never executes SQL or returns input text. */
+export const scanMigrationSql = (source) => {
+    const lexical = lexMigrationSql(source);
+    const reasons = new Set(lexical.unknownReasons);
+    // Runtime-dependent plain-string escape settings can change statement boundaries.
+    if (lexical.ambiguousQuotes)
+        return {
+            complete: false,
+            findings: [],
+            unknownReasons: [...reasons].sort(),
+        };
+    const findings = [];
+    const findingKeys = new Set();
+    const add = (rule, token) => {
+        const key = `${rule}:${token.line}:${token.column}`;
+        if (findingKeys.has(key))
+            return;
+        if (findings.length >= 1000) {
+            reasons.add("input_limit");
+            return;
+        }
+        findingKeys.add(key);
+        findings.push({
+            rule,
+            severity: ["not_null", "new_constraint"].includes(rule)
+                ? "warning"
+                : "danger",
+            line: token.line,
+            column: token.column,
+        });
+    };
+    const unsupported = () => {
+        reasons.add("unsupported_sql");
+    };
+    const malformed = () => {
+        reasons.add("malformed_sql");
+    };
+    const cascade = (tokens, trailing = true) => {
+        const last = tokens.at(-1);
+        if (trailing && word(last, "CASCADE"))
+            add("cascade", last);
+        for (let index = 2; index < tokens.length; index += 1)
+            if (word(tokens[index], "CASCADE") &&
+                (word(tokens[index - 1], "DELETE") ||
+                    word(tokens[index - 1], "UPDATE")) &&
+                word(tokens[index - 2], "ON"))
+                add("cascade", tokens[index]);
+    };
+    const relationList = (tokens, start) => {
+        if (start >= tokens.length)
+            return false;
+        let index = start;
+        while (index < tokens.length) {
+            if (word(tokens[index], "ONLY"))
+                index += 1;
+            const end = qualifiedNameEnd(tokens, index);
+            if (end === index)
+                return false;
+            index = end;
+            if (tokens[index]?.value === "*")
+                index += 1;
+            if (tokens[index]?.value !== ",")
+                break;
+            index += 1;
+            if (index === tokens.length)
+                return false;
+        }
+        if ((word(tokens[index], "RESTART") || word(tokens[index], "CONTINUE")) &&
+            word(tokens[index + 1], "IDENTITY"))
+            index += 2;
+        if (word(tokens[index], "CASCADE") || word(tokens[index], "RESTRICT"))
+            index += 1;
+        return index === tokens.length;
+    };
+    const analyze = (tokens, depth) => {
+        if (tokens.length === 0)
+            return;
+        const top = topTokens(tokens, depth);
+        const first = top[0];
+        if (!first || first.kind !== "word") {
+            unsupported();
+            return;
+        }
+        if (word(first, "WITH")) {
+            let index = 1;
+            if (word(tokens[index], "RECURSIVE"))
+                index += 1;
+            const afterGroup = (start) => {
+                const opening = tokens[start];
+                if (opening?.value !== "(")
+                    return start;
+                const close = tokens.findIndex((token, candidate) => candidate > start &&
+                    token.value === ")" &&
+                    token.depth === opening.depth);
+                return close < 0 ? start : close + 1;
+            };
+            while (index < tokens.length) {
+                if (!name(tokens[index])) {
+                    unsupported();
+                    return;
+                }
+                index += 1;
+                if (tokens[index]?.value === "(") {
+                    const next = afterGroup(index);
+                    if (next === index) {
+                        malformed();
+                        return;
+                    }
+                    index = next;
+                }
+                if (!word(tokens[index], "AS")) {
+                    unsupported();
+                    return;
+                }
+                index += 1;
+                if (word(tokens[index], "NOT")) {
+                    index += 1;
+                    if (!word(tokens[index], "MATERIALIZED")) {
+                        unsupported();
+                        return;
+                    }
+                }
+                if (word(tokens[index], "MATERIALIZED"))
+                    index += 1;
+                const end = afterGroup(index);
+                if (end === index) {
+                    unsupported();
+                    return;
+                }
+                if (end === index + 2) {
+                    malformed();
+                    return;
+                }
+                analyze(tokens.slice(index + 1, end - 1), depth + 1);
+                index = end;
+                if (tokens[index]?.value !== ",")
+                    break;
+                index += 1;
+            }
+            if (index >= tokens.length) {
+                malformed();
+                return;
+            }
+            analyze(tokens.slice(index), depth);
+            return;
+        }
+        if (word(first, "DROP") && word(top[1], "TABLE")) {
+            let start = 2;
+            if (word(top[start], "IF") && word(top[start + 1], "EXISTS"))
+                start += 2;
+            if (!relationList(top, start)) {
+                malformed();
+                return;
+            }
+            add("drop_table", first);
+            cascade(top);
+            return;
+        }
+        if (word(first, "TRUNCATE")) {
+            const start = word(top[1], "TABLE") ? 2 : 1;
+            if (!relationList(top, start)) {
+                malformed();
+                return;
+            }
+            add("truncate", first);
+            cascade(top);
+            return;
+        }
+        if (word(first, "UPDATE") || word(first, "DELETE")) {
+            const update = word(first, "UPDATE");
+            let start = update ? 1 : 2;
+            if (!update && !word(top[1], "FROM")) {
+                malformed();
+                return;
+            }
+            if (word(top[start], "ONLY"))
+                start += 1;
+            const end = qualifiedNameEnd(top, start);
+            if (end === start) {
+                malformed();
+                return;
+            }
+            const where = top.findIndex((token, index) => index >= end && word(token, "WHERE"));
+            const returning = top.findIndex((token, index) => index >= end && word(token, "RETURNING"));
+            const set = top.findIndex((token, index) => index >= end && word(token, "SET"));
+            const boundary = Math.min(...[where, returning, top.length].filter((position) => position >= 0));
+            const assignment = top.slice(set + 1, boundary);
+            const equals = assignment.findIndex((token) => token.value === "=");
+            if (update &&
+                (set < 0 ||
+                    equals <= 0 ||
+                    equals === assignment.length - 1 ||
+                    assignment.at(-1)?.value === ",")) {
+                malformed();
+                return;
+            }
+            if (where >= 0 &&
+                (where === top.length - 1 || (returning >= 0 && returning <= where + 1))) {
+                malformed();
+                return;
+            }
+            if (where < 0 || (returning >= 0 && returning < where))
+                add(update ? "broad_update" : "broad_delete", first);
+            return;
+        }
+        if (word(first, "ALTER") && word(top[1], "TABLE")) {
+            let index = 2;
+            if (word(top[index], "IF") && word(top[index + 1], "EXISTS"))
+                index += 2;
+            if (word(top[index], "ONLY"))
+                index += 1;
+            const end = qualifiedNameEnd(top, index);
+            if (end === index) {
+                malformed();
+                return;
+            }
+            index = end + (top[end]?.value === "*" ? 1 : 0);
+            if (index >= top.length) {
+                malformed();
+                return;
+            }
+            while (index < top.length) {
+                const comma = top.findIndex((token, candidate) => candidate >= index && token.value === ",");
+                const clause = top.slice(index, comma < 0 ? undefined : comma);
+                if (clause.length === 0) {
+                    malformed();
+                    return;
+                }
+                if (word(clause[0], "DROP")) {
+                    let column = 1;
+                    if (word(clause[column], "COLUMN"))
+                        column += 1;
+                    if (word(clause[column], "IF") && word(clause[column + 1], "EXISTS"))
+                        column += 2;
+                    if (word(clause[1], "CONSTRAINT"))
+                        unsupported();
+                    else if (name(clause[column]) &&
+                        (column + 1 === clause.length ||
+                            ((word(clause[column + 1], "CASCADE") ||
+                                word(clause[column + 1], "RESTRICT")) &&
+                                column + 2 === clause.length)))
+                        add("drop_column", clause[0]);
+                    else
+                        malformed();
+                    cascade(clause);
+                }
+                else if (word(clause[0], "ALTER")) {
+                    const column = word(clause[1], "COLUMN") ? 2 : 1;
+                    if (name(clause[column]) &&
+                        word(clause[column + 1], "SET") &&
+                        word(clause[column + 2], "NOT") &&
+                        word(clause[column + 3], "NULL") &&
+                        column + 4 === clause.length)
+                        add("not_null", clause[column + 2]);
+                    else
+                        unsupported();
+                }
+                else if (word(clause[0], "ADD")) {
+                    let caseDepth = 0;
+                    let constraint = false;
+                    for (let cursor = 1; cursor < clause.length; cursor += 1) {
+                        const token = clause[cursor];
+                        if (word(token, "CASE"))
+                            caseDepth += 1;
+                        if (word(token, "END"))
+                            caseDepth = Math.max(0, caseDepth - 1);
+                        if (caseDepth > 0)
+                            continue;
+                        if (word(token, "NOT") &&
+                            word(clause[cursor + 1], "NULL") &&
+                            !word(clause[cursor - 1], "IS"))
+                            add("not_null", token);
+                        if (["CONSTRAINT", "CHECK", "UNIQUE", "REFERENCES", "EXCLUDE"].some((keyword) => word(token, keyword)) ||
+                            (word(token, "PRIMARY") && word(clause[cursor + 1], "KEY")) ||
+                            (word(token, "FOREIGN") && word(clause[cursor + 1], "KEY")))
+                            constraint = true;
+                    }
+                    if (constraint)
+                        add("new_constraint", clause[0]);
+                    // Column definitions/types/expressions are deliberately not parsed.
+                    unsupported();
+                    cascade(clause, false);
+                }
+                else
+                    unsupported();
+                if (comma < 0)
+                    break;
+                index = comma + 1;
+                if (index >= top.length)
+                    malformed();
+            }
+            return;
+        }
+        // Other DDL can contain a meaningful trailing CASCADE, but remains unknown.
+        if (word(first, "DROP")) {
+            let target = 2;
+            if ((word(top[1], "MATERIALIZED") && word(top[2], "VIEW")) ||
+                (word(top[1], "FOREIGN") && word(top[2], "TABLE")))
+                target += 1;
+            if (word(top[target], "IF") && word(top[target + 1], "EXISTS"))
+                target += 2;
+            const end = qualifiedNameEnd(top, target);
+            if (end > target && end === top.length - 1 && word(top[end], "CASCADE"))
+                cascade(top);
+        }
+        if (word(first, "CREATE") && word(top[1], "TABLE"))
+            cascade(tokens, false);
+        unsupported();
+    };
+    let start = 0;
+    let atomicDepth = 0;
+    let opaqueBody = false;
+    for (let index = 0; index <= lexical.tokens.length; index += 1) {
+        const token = lexical.tokens[index];
+        let routine = start + 1;
+        if (word(lexical.tokens[routine], "OR") &&
+            word(lexical.tokens[routine + 1], "REPLACE"))
+            routine += 2;
+        const routineStatement = word(lexical.tokens[start], "CREATE") &&
+            (word(lexical.tokens[routine], "FUNCTION") ||
+                word(lexical.tokens[routine], "PROCEDURE"));
+        if (routineStatement &&
+            token?.depth === 0 &&
+            word(token, "BEGIN") &&
+            word(lexical.tokens[index + 1], "ATOMIC")) {
+            opaqueBody = true;
+            atomicDepth += 1;
+        }
+        else if (opaqueBody &&
+            token?.depth === 0 &&
+            (word(token, "BEGIN") || word(token, "CASE")))
+            atomicDepth += 1;
+        else if (opaqueBody && token?.depth === 0 && word(token, "END"))
+            atomicDepth -= 1;
+        if (index === lexical.tokens.length ||
+            (token?.value === ";" && token.depth === 0 && atomicDepth === 0)) {
+            const statement = lexical.tokens.slice(start, index);
+            if (opaqueBody)
+                unsupported();
+            else if (index !== lexical.tokens.length ||
+                !lexical.unknownReasons.some((reason) => reason === "input_limit" || reason === "malformed_sql"))
+                analyze(statement, 0);
+            start = index + 1;
+            opaqueBody = false;
+        }
+    }
+    if (atomicDepth > 0)
+        malformed();
+    findings.sort((left, right) => left.line - right.line ||
+        left.column - right.column ||
+        left.rule.localeCompare(right.rule));
+    return {
+        complete: reasons.size === 0,
+        findings,
+        unknownReasons: [...reasons].sort(),
+    };
+};

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

@@ -4,6 +4,7 @@
  * this module is reusable script infrastructure.
  */
 import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import { readMigrationFileInventory } from "./migration_history.mjs";
 export declare const buildRehearsalPlan: (options?: RehearsalConfigPathOptions) => Promise<{
     config: {
         schemaVersion: 1;
@@ -228,7 +229,7 @@ export declare const inspectRehearsalBaseline: (options?: RehearsalConfigPathOpt
         };
     };
 }>;
-export declare const inspectRehearsalMigrations: (options?: RehearsalConfigPathOptions) => Promise<{
+export declare const inspectRehearsalMigrations: (options?: RehearsalConfigPathOptions, inventoryReader?: typeof readMigrationFileInventory) => Promise<{
     baselineGenerationId: string;
     baselineCutoff: string;
     candidateSha256: string;

package/dist/src/runtime/plan.mjs

@@ -155,7 +155,7 @@ const assertConfiguredCommand = async ({ command, projectRoot, }) => {
     }
     return `package script ${scriptName} exists`;
 };
-const loadPlanInputs = async (options = {}) => {
+const loadPlanInputs = async (options = {}, inventoryReader = readMigrationFileInventory) => {
     const loaded = await loadRehearsalConfig(options);
     const [baseline, policyBytes] = await Promise.all([
         verifyActiveBaseline({
@@ -167,7 +167,7 @@ const loadPlanInputs = async (options = {}) => {
         bytes: policyBytes,
         expectedSha256: baseline.sanitizationPolicySha256,
     });
-    const currentFiles = await readMigrationFileInventory(new URL("./", pathToFileURL(`${loaded.paths.migrationDirectory}/`)));
+    const currentFiles = await inventoryReader(new URL("./", pathToFileURL(`${loaded.paths.migrationDirectory}/`)));
     const candidateReceipt = createCandidateMigrationReceipt({
         baselineManifest: baseline,
         currentFiles,
@@ -363,8 +363,8 @@ export const inspectRehearsalBaseline = async (options = {}) => {
         review: plan.baselineReview,
     };
 };
-export const inspectRehearsalMigrations = async (options = {}) => {
-    const inputs = await loadPlanInputs(options);
+export const inspectRehearsalMigrations = async (options = {}, inventoryReader = readMigrationFileInventory) => {
+    const inputs = await loadPlanInputs(options, inventoryReader);
     return {
         baselineGenerationId: inputs.baseline.generationId,
         baselineCutoff: inputs.baseline.migrationCutoff,

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

@@ -36,7 +36,7 @@ declare const candidateSummary: (inspection: MigrationInspection) => Readonly<{
         status: string;
     }[];
 }>;
-export declare const inspectRuntimeTopologyCandidates: (options?: RehearsalConfigPathOptions) => Promise<Readonly<{
+export declare const inspectRuntimeTopologyCandidates: (options?: RehearsalConfigPathOptions, inspectMigrations?: typeof inspectRehearsalMigrations) => Promise<Readonly<{
     topology: Readonly<{
         projectRoot: string;
         primary: RuntimeTopologyTarget;

package/dist/src/runtime/topology.mjs

@@ -103,13 +103,13 @@ const candidateSummary = (inspection) => {
         candidates: Object.freeze(candidates),
     });
 };
-export const inspectRuntimeTopologyCandidates = async (options = {}) => {
+export const inspectRuntimeTopologyCandidates = async (options = {}, inspectMigrations = inspectRehearsalMigrations) => {
     const topology = await loadRuntimeTopology(options);
     const targets = [];
     for (const target of topology.targets) {
         targets.push(Object.freeze({
             ...target,
-            summary: candidateSummary(await inspectRehearsalMigrations({
+            summary: candidateSummary(await inspectMigrations({
                 projectRoot: topology.projectRoot,
                 configPath: target.configPath,
             })),

package/dist/src/shared/cancellation.mjs

@@ -9,6 +9,7 @@ export const OPERATION_CANCELLATION_SIGNALS = [
 ];
 const CANCELLABLE_COMMANDS = new Set([
     "migrate",
+    "measure impact",
     "open",
     "refresh",
     "reset",

package/dist/src/shared/held_path_ancestry.d.mts

@@ -0,0 +1,7 @@
+export declare const HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES = 128;
+export interface HeldPathAncestry {
+    readonly path: string;
+    assertUnchanged(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare const holdPathAncestry: (directory: string) => Promise<HeldPathAncestry>;

package/dist/src/shared/held_path_ancestry.mjs

@@ -0,0 +1,110 @@
+/**
+ * Timestamp-based concurrent-change guard for a canonical directory ancestry.
+ * This is not atomic openat resolution or a sandbox: it cannot prevent every
+ * transient access or privileged timestamp manipulation. Callers retain their
+ * own project-containment, regular-file and exact-input identity checks, use
+ * only `path` for reads, assert before/after those reads, and close in finally.
+ */
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+export const HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES = 128;
+const unavailable = () => new Error("Path ancestry is unavailable, unsafe or changed.");
+const identity = (details) => {
+    if (!details.isDirectory() ||
+        details.isSymbolicLink() ||
+        typeof details.dev !== "bigint" ||
+        typeof details.ino !== "bigint" ||
+        typeof details.ctimeNs !== "bigint" ||
+        typeof details.mtimeNs !== "bigint")
+        throw unavailable();
+    return {
+        dev: details.dev,
+        ino: details.ino,
+        ctimeNs: details.ctimeNs,
+        mtimeNs: details.mtimeNs,
+    };
+};
+const same = (left, right) => left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.ctimeNs === right.ctimeNs &&
+    left.mtimeNs === right.mtimeNs;
+export const holdPathAncestry = async (directory) => {
+    const handles = [];
+    const entries = [];
+    let closed = false;
+    let closing;
+    const close = () => {
+        if (closing)
+            return closing;
+        closed = true;
+        closing = (async () => {
+            let failed = false;
+            for (const handle of handles.splice(0).reverse()) {
+                try {
+                    await handle.close();
+                }
+                catch {
+                    failed = true;
+                }
+            }
+            if (failed)
+                throw unavailable();
+        })();
+        return closing;
+    };
+    try {
+        if (!isAbsolute(directory))
+            throw unavailable();
+        const path = resolve(directory);
+        const root = parse(path).root;
+        const segments = relative(root, path).split(sep).filter(Boolean);
+        if (segments.length + 1 > HELD_PATH_ANCESTRY_MAXIMUM_DIRECTORIES)
+            throw unavailable();
+        // Reject aliases and all symlink ancestors, including ancestors above the
+        // caller's project root. Root aliases must be canonicalized by the caller.
+        if ((await realpath(path)) !== path)
+            throw unavailable();
+        const paths = [root];
+        for (const segment of segments)
+            paths.push(join(paths.at(-1), segment));
+        for (const current of paths) {
+            const before = identity(await lstat(current, { bigint: true }));
+            const handle = await open(current, constants.O_RDONLY |
+                constants.O_DIRECTORY |
+                constants.O_NOFOLLOW |
+                constants.O_NONBLOCK);
+            // Retain immediately: a later stat failure must still close this handle.
+            handles.push(handle);
+            const opened = identity(await handle.stat({ bigint: true }));
+            const after = identity(await lstat(current, { bigint: true }));
+            if (!same(before, opened) || !same(before, after))
+                throw unavailable();
+            entries.push({ path: current, handle, identity: before });
+        }
+        const assertUnchanged = async () => {
+            try {
+                if (closed || (await realpath(path)) !== path)
+                    throw unavailable();
+                for (const entry of entries) {
+                    const held = identity(await entry.handle.stat({ bigint: true }));
+                    const lexical = identity(await lstat(entry.path, { bigint: true }));
+                    if (!same(entry.identity, held) || !same(entry.identity, lexical))
+                        throw unavailable();
+                }
+                if ((await realpath(path)) !== path)
+                    throw unavailable();
+            }
+            catch {
+                await close().catch(() => { });
+                throw unavailable();
+            }
+        };
+        await assertUnchanged();
+        return Object.freeze({ path, assertUnchanged, close });
+    }
+    catch {
+        await close().catch(() => { });
+        throw unavailable();
+    }
+};

package/dist/src/shared/operation_guard.mjs

@@ -21,6 +21,7 @@ const OPERATION_KINDS = new Set([
     "identity connect",
     "init",
     "migrate",
+    "measure impact",
     "open",
     "privacy key",
     "refresh",

package/dist/src/targets/migration_impact_runtime.d.mts

@@ -0,0 +1,22 @@
+import type { BaselineManifest } from "../baseline/artifact.mjs";
+import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
+import { runOwnedProcess } from "../shared/owned_process.mjs";
+export type MigrationImpactRuntimeFailureReason = "runtime_unavailable" | "ownership_mismatch" | "stale_runtime" | "query_failed" | "lock_timeout" | "statement_timeout" | "transaction_timeout" | "cancelled";
+export declare class MigrationImpactRuntimeError extends Error {
+    readonly reason: MigrationImpactRuntimeFailureReason;
+    constructor(reason: MigrationImpactRuntimeFailureReason);
+}
+export interface MigrationImpactRuntime {
+    readonly identitySha256: string;
+    runSql(sql: string | (() => string)): Promise<string>;
+    assertCurrent(): Promise<void>;
+}
+export interface OpenMigrationImpactRuntimeOptions {
+    readonly projectRoot: string;
+    readonly target: RuntimeTopologyTarget;
+    readonly baseline: BaselineManifest;
+    readonly signal?: AbortSignal;
+    readonly runProcessImplementation?: typeof runOwnedProcess;
+}
+/** No lifecycle, adapter, source-reader, URL or credential-file access is permitted here. */
+export declare function openMigrationImpactRuntime(options: OpenMigrationImpactRuntimeOptions): Promise<MigrationImpactRuntime>;