@rehearsal-db/core 1.1.0 → 1.2.0

package/dist/src/runtime/migration_impact_queries.mjs

@@ -0,0 +1,270 @@
+import { nativeMigrationImpactIndexes, nativeMigrationImpactStatistics, nativeMigrationImpactComparison, } from "./migration_impact_catalog.mjs";
+export const MIGRATION_IMPACT_LIMITS = Object.freeze({
+    maximumMeasurements: 100,
+    lockTimeoutMilliseconds: 1_000,
+    statementTimeoutMilliseconds: 5_000,
+    totalTimeoutMilliseconds: 30_000,
+    maximumOutputBytes: 131_072,
+    maximumScriptBytes: 262_144,
+});
+const identifier = (value) => {
+    if (typeof value !== "string" || !/^[a-z_][a-z0-9_$]{0,62}$/u.test(value))
+        throw new Error("The private measurement identifier is unsupported.");
+    return value;
+};
+const quoted = (value) => `"${identifier(value)}"`;
+const literal = (value) => `'${identifier(value)}'`;
+const relationName = (relation) => `${quoted(relation.schema)}.${quoted(relation.name)}`;
+const relationLiteral = (relation) => `'${relationName(relation)}'`;
+const relationPredicate = (relation, alias) => `${alias}.relnamespace = (select oid from pg_catalog.pg_namespace where nspname = ${literal(relation.schema)})
+    and ${alias}.relname = ${literal(relation.name)}
+    and ${alias}.relkind = 'r' and ${alias}.relpersistence in ('p', 'u')
+    and not ${alias}.relrowsecurity and not ${alias}.relispartition
+    and ${alias}.relam = (select oid from pg_catalog.pg_am where amname = 'heap')
+    and not exists (select 1 from pg_catalog.pg_inherits h
+      where h.inhparent = ${alias}.oid or h.inhrelid = ${alias}.oid)
+    and pg_catalog.to_regclass(${relationLiteral(relation)})::oid = ${alias}.oid
+    and ${nativeMigrationImpactIndexes(alias)}
+    and ${nativeMigrationImpactStatistics(alias)}`;
+const columnPredicate = (relationAlias, column, compare) => `exists (
+    select 1 from pg_catalog.pg_attribute a
+    join pg_catalog.pg_type t on t.oid = a.atttypid
+    join pg_catalog.pg_namespace tn on tn.oid = t.typnamespace
+    where a.attrelid = ${relationAlias}.oid and a.attname = ${literal(column)}
+      and a.attnum > 0 and not a.attisdropped and a.attgenerated in ('', 's')
+      and tn.nspname = 'pg_catalog' and t.oid < 16384 and t.typbasetype = 0
+      and t.typname in ('bool', 'int2', 'int4', 'int8', 'numeric', 'float4', 'float8',
+        'text', ${compare ? "" : "'varchar', 'bpchar',"} 'uuid', 'date', 'timestamp', 'timestamptz')
+      ${compare ? `and ${nativeMigrationImpactComparison("t")}` : ""}
+      ${compare ? `and (a.attcollation = 0 or exists (select 1 from pg_catalog.pg_collation co join pg_catalog.pg_namespace cn on cn.oid = co.collnamespace where co.oid = a.attcollation and co.oid < 16384 and cn.nspname = 'pg_catalog' and co.collisdeterministic))` : ""}
+  )`;
+const validateTask = (task) => {
+    relationName(task.relation);
+    if (!Number.isSafeInteger(task.line) ||
+        task.line < 1 ||
+        !Number.isSafeInteger(task.column) ||
+        task.column < 1)
+        throw new Error("The private measurement location is unsupported.");
+    const operations = {
+        rows: ["drop_table", "truncate", "broad_delete"],
+        populated: ["drop_column"],
+        nulls: ["not_null"],
+        duplicate_rows: ["new_constraint"],
+        orphan_rows: ["new_constraint"],
+    };
+    if (!operations[task.metric]?.includes(task.operation))
+        throw new Error("The private measurement kind is unsupported.");
+    if (task.metric !== "rows") {
+        if (!Array.isArray(task.columns) ||
+            task.columns.length < 1 ||
+            task.columns.length > 8 ||
+            new Set(task.columns).size !== task.columns.length ||
+            (["populated", "nulls"].includes(task.metric) &&
+                task.columns.length !== 1))
+            throw new Error("The private measurement columns are unsupported.");
+        task.columns.forEach(identifier);
+    }
+    if (task.metric === "orphan_rows") {
+        relationName(task.referencedRelation);
+        if (!Array.isArray(task.referencedColumns) ||
+            task.referencedColumns.length !== task.columns.length ||
+            new Set(task.referencedColumns).size !== task.referencedColumns.length)
+            throw new Error("The private measurement reference is unsupported.");
+        task.referencedColumns.forEach(identifier);
+    }
+};
+const metadataCheck = (task, relationIds) => {
+    const compare = ["duplicate_rows", "orphan_rows"].includes(task.metric);
+    const expectedOid = (relation, alias) => `${alias}.oid = :'impact_relation_${relationIds.get(relationName(relation))}_oid'::pg_catalog.oid`;
+    const predicates = [
+        relationPredicate(task.relation, "r"),
+        expectedOid(task.relation, "r"),
+    ];
+    if (task.metric !== "rows")
+        predicates.push(...task.columns.map((column) => columnPredicate("r", column, compare)));
+    if (task.metric === "orphan_rows") {
+        const pairedColumns = task.columns.map((column, index) => `exists (select 1 from pg_catalog.pg_attribute ca join pg_catalog.pg_attribute pa
+        on pa.attrelid = p.oid and pa.attname = ${literal(task.referencedColumns[index])}
+        where ca.attrelid = r.oid and ca.attname = ${literal(column)}
+          and ca.atttypid = pa.atttypid and ca.attcollation = pa.attcollation)`);
+        predicates.push(`exists (select 1 from pg_catalog.pg_class p where
+      ${relationPredicate(task.referencedRelation, "p")} and ${expectedOid(task.referencedRelation, "p")} and
+      ${task.referencedColumns.map((column) => columnPredicate("p", column, true)).join(" and ")} and
+      ${pairedColumns.join(" and ")})`);
+    }
+    return `select exists (select 1 from pg_catalog.pg_class r where ${predicates.join(" and ")}) as ok`;
+};
+const countQuery = (task) => {
+    const table = relationName(task.relation);
+    if (task.metric === "rows")
+        return `select pg_catalog.count(*)::text as count from only ${table}`;
+    if (task.metric === "nulls" || task.metric === "populated")
+        return `select pg_catalog.count(*)::text as count from only ${table}
+      where ${quoted(task.columns[0])} is ${task.metric === "populated" ? "not " : ""}null`;
+    const populated = task.columns
+        .map((column) => `c.${quoted(column)} is not null`)
+        .join(" and ");
+    if (task.metric === "duplicate_rows")
+        return `select coalesce(pg_catalog.sum(n), 0)::text as count from (
+      select pg_catalog.count(*) as n from only ${table} c where ${populated}
+      group by ${task.columns.map((column) => `c.${quoted(column)}`).join(", ")}
+      having pg_catalog.count(*) > 1) duplicates`;
+    const equal = task.columns
+        .map((column, index) => `p.${quoted(task.referencedColumns[index])} operator(pg_catalog.=) c.${quoted(column)}`)
+        .join(" and ");
+    return `select pg_catalog.count(*)::text as count from only ${table} c
+    where ${populated} and not exists (select 1 from only ${relationName(task.referencedRelation)} p where ${equal})`;
+};
+/** One consistent current-row snapshot. No pending migration statement is executed. */
+export const buildMigrationImpactScript = (tasks, transactionTimeoutMilliseconds = MIGRATION_IMPACT_LIMITS.totalTimeoutMilliseconds) => {
+    if (tasks.length > MIGRATION_IMPACT_LIMITS.maximumMeasurements)
+        throw new Error("The measurement count exceeds its fixed bound.");
+    tasks.forEach(validateTask);
+    if (!Number.isSafeInteger(transactionTimeoutMilliseconds) ||
+        transactionTimeoutMilliseconds < 1 ||
+        transactionTimeoutMilliseconds >
+            MIGRATION_IMPACT_LIMITS.totalTimeoutMilliseconds)
+        throw new Error("The server transaction deadline exceeds its fixed bound.");
+    const relations = [
+        ...new Map(tasks.flatMap((task) => [
+            task.relation,
+            ...(task.metric === "orphan_rows" ? [task.referencedRelation] : []),
+        ].map((relation) => [relationName(relation), relation]))).entries(),
+    ].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    const relationIds = new Map(relations.map(([name], index) => [name, index]));
+    const script = [
+        "\\set ON_ERROR_STOP on",
+        "set default_transaction_read_only = on;",
+        "set lock_timeout = '1s';",
+        "set statement_timeout = '5s';",
+        "set idle_in_transaction_session_timeout = '5s';",
+        "set search_path = pg_catalog;",
+        "set row_security = off;",
+        "set max_parallel_workers_per_gather = 0;",
+        "set work_mem = '1MB';",
+        "set temp_file_limit = '8MB';",
+        "set constraint_exclusion = off;",
+        "select pg_catalog.current_setting('server_version_num')::integer >= 170000 as supported \\gset impact_server_",
+        "\\if :impact_server_supported",
+        `set transaction_timeout = '${transactionTimeoutMilliseconds}ms';`,
+        "select pg_catalog.clock_timestamp()::text as started \\gset impact_clock_",
+        "begin isolation level read committed read only;",
+        ...relations.map(([, relation], index) => `with eligible as (select r.oid from pg_catalog.pg_class r where ${relationPredicate(relation, "r")})
+      select exists (select 1 from eligible) as ok, coalesce((select oid from eligible), 0)::pg_catalog.oid as oid \\gset impact_relation_${index}_`),
+        "rollback;",
+        // Preflight must not freeze the later repeatable-read catalog snapshot.
+        `select greatest(1, least(${transactionTimeoutMilliseconds}, ${transactionTimeoutMilliseconds} - elapsed))::text as milliseconds,
+      elapsed < ${transactionTimeoutMilliseconds} as available from
+      (select pg_catalog.ceil(extract(epoch from (pg_catalog.clock_timestamp() - :'impact_clock_started'::pg_catalog.timestamptz)) * 1000) as elapsed) budget \\gset impact_remaining_`,
+        "\\if :impact_remaining_available",
+        "begin isolation level repeatable read read only;",
+        "set local transaction_timeout = :'impact_remaining_milliseconds';",
+        // Schema names also participate in query resolution. A database-local
+        // namespace-catalog lock prevents schema rename/swap after the checks;
+        // relation locks alone do not stabilize that mapping.
+        "lock table pg_catalog.pg_namespace in share mode;",
+        // Globally ordered strong locks exclude ordinary/concurrent index and statistics
+        // DDL before the first repeatable-read SELECT establishes the count snapshot.
+        // A name swapped to a view can transiently lock its dependencies; the retained
+        // OID/ordinary-table checks still prohibit reading it or executing its query.
+        ...relations.flatMap(([name], index) => [
+            `\\if :impact_relation_${index}_ok`,
+            `lock table only ${name} in share row exclusive mode;`,
+            "\\endif",
+        ]),
+        `select pg_catalog.json_build_object('snapshotAt', pg_catalog.to_char(pg_catalog.statement_timestamp() at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'));`,
+    ];
+    tasks.forEach((task, index) => {
+        const unknown = `select pg_catalog.json_build_object('index', ${index}, 'count', null, 'reason', 'unsupported_runtime_metadata');`;
+        script.push(`${metadataCheck(task, relationIds)} \\gset locked_${index}_`, `\\if :locked_${index}_ok`, `select pg_catalog.json_build_object('index', ${index}, 'count', measured.count, 'reason', null) from (${countQuery(task)}) measured;`, "\\else", unknown, "\\endif");
+    });
+    script.push("rollback;", "\\else", "select pg_catalog.json_build_object('totalTimeout', true);", "\\endif", "\\else", "select pg_catalog.json_build_object('unsupportedServerVersion', true);", "\\endif", "");
+    const result = script.join("\n");
+    if (Buffer.byteLength(result) > MIGRATION_IMPACT_LIMITS.maximumScriptBytes)
+        throw new Error("The fixed measurement script exceeds its byte bound.");
+    return result;
+};
+export const parseMigrationImpactBatchOutput = (output, expectedCount) => {
+    const invalid = () => {
+        throw new Error("The sandbox returned an unsupported aggregate snapshot.");
+    };
+    if (Buffer.byteLength(output) > MIGRATION_IMPACT_LIMITS.maximumOutputBytes)
+        return invalid();
+    const lines = output.trim().split(/\r?\n/u);
+    let header;
+    try {
+        header = JSON.parse(lines.shift() ?? "");
+    }
+    catch {
+        return invalid();
+    }
+    if (!header || typeof header !== "object" || Array.isArray(header))
+        return invalid();
+    const value = header;
+    if ((Object.keys(value).join(",") === "unsupportedServerVersion" &&
+        value.unsupportedServerVersion === true) ||
+        (Object.keys(value).join(",") === "totalTimeout" &&
+            value.totalTimeout === true)) {
+        if (lines.length ||
+            !Number.isSafeInteger(expectedCount) ||
+            expectedCount < 0 ||
+            expectedCount > MIGRATION_IMPACT_LIMITS.maximumMeasurements)
+            return invalid();
+        return {
+            snapshotAt: null,
+            counts: Array.from({ length: expectedCount }, (_, index) => ({
+                index,
+                count: null,
+                reason: value.totalTimeout === true
+                    ? "total_timeout"
+                    : "unsupported_server_version",
+            })),
+        };
+    }
+    if (Object.keys(value).join(",") !== "snapshotAt" ||
+        typeof value.snapshotAt !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value.snapshotAt) ||
+        !Number.isFinite(Date.parse(value.snapshotAt)) ||
+        new Date(value.snapshotAt).toISOString() !== value.snapshotAt)
+        return invalid();
+    return {
+        snapshotAt: value.snapshotAt,
+        counts: parseMigrationImpactOutput(lines.join("\n"), expectedCount),
+    };
+};
+export const parseMigrationImpactOutput = (output, expectedCount) => {
+    const invalid = () => {
+        throw new Error("The sandbox returned an unsupported aggregate report.");
+    };
+    if (!Number.isSafeInteger(expectedCount) ||
+        expectedCount < 0 ||
+        expectedCount > MIGRATION_IMPACT_LIMITS.maximumMeasurements ||
+        Buffer.byteLength(output) > MIGRATION_IMPACT_LIMITS.maximumOutputBytes)
+        return invalid();
+    const lines = output.trim() ? output.trim().split(/\r?\n/u) : [];
+    if (lines.length !== expectedCount)
+        return invalid();
+    return lines.map((line, index) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return invalid();
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return invalid();
+        const value = parsed;
+        if (Object.keys(value).sort().join(",") !== "count,index,reason" ||
+            value.index !== index)
+            return invalid();
+        if (value.count === null && value.reason === "unsupported_runtime_metadata")
+            return { index, count: null, reason: value.reason };
+        if (typeof value.count !== "string" ||
+            !/^(?:0|[1-9][0-9]{0,18})$/u.test(value.count) ||
+            BigInt(value.count) > 9223372036854775807n ||
+            value.reason !== null)
+            return invalid();
+        return { index, count: value.count, reason: null };
+    });
+};

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;
+};