rawsql-ts 0.21.0 → 0.22.0

package/dist/esm/transformers/SSSQLFilterBuilder.js

@@ -2,6 +2,8 @@ import { WhereClause, SubQuerySource, TableSource } from "../models/Clause";
 import { SimpleSelectQuery } from "../models/SelectQuery";
 import { BinaryExpression, ColumnReference, IdentifierString, InlineQuery, LiteralValue, ParameterExpression, ParenExpression, RawString, UnaryExpression } from "../models/ValueComponent";
 import { SelectQueryParser } from "../parsers/SelectQueryParser";
+import { SqlTokenizer } from "../parsers/SqlTokenizer";
+import { TokenType } from "../models/Lexeme";
 import { UpstreamSelectQueryFinder } from "./UpstreamSelectQueryFinder";
 import { ColumnReferenceCollector } from "./ColumnReferenceCollector";
 import { SelectableColumnCollector, DuplicateDetectionMode } from "./SelectableColumnCollector";
@@ -13,6 +15,222 @@ const SUPPORTED_SCALAR_OPERATORS = new Set(["=", "<>", "<", "<=", ">", ">=", "li
 let formatter = null;
 const normalizeIdentifier = (value) => value.trim().toLowerCase();
 const normalizeSql = (value) => value.replace(/\s+/g, " ").trim().toLowerCase();
+const normalizeRewriteTokenType = (lexeme) => {
+    if ((lexeme.type & TokenType.Command) !== 0) {
+        return TokenType.Command;
+    }
+    if ((lexeme.type & TokenType.Identifier) !== 0) {
+        return TokenType.Identifier;
+    }
+    return lexeme.type;
+};
+const normalizeRewriteTokenValue = (lexeme) => {
+    if ((lexeme.type & TokenType.Command) !== 0) {
+        return lexeme.value.toLowerCase();
+    }
+    return lexeme.value;
+};
+const tokenizeForRewritePlan = (sql) => {
+    return new SqlTokenizer(sql).tokenize().map(lexeme => ({
+        type: normalizeRewriteTokenType(lexeme),
+        value: normalizeRewriteTokenValue(lexeme)
+    }));
+};
+const tokenSequencesEqual = (left, right) => {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((token, index) => {
+        const other = right[index];
+        return other !== undefined && token.type === other.type && token.value === other.value;
+    });
+};
+const collectCommentFragments = (sql) => {
+    return new SqlTokenizer(sql).tokenize().flatMap(lexeme => {
+        if (lexeme.positionedComments) {
+            return lexeme.positionedComments.flatMap(positioned => positioned.comments);
+        }
+        return lexeme.comments ? [...lexeme.comments] : [];
+    });
+};
+const commentsPreservedInOrder = (before, after) => {
+    let cursor = 0;
+    for (const comment of before) {
+        const foundAt = after.indexOf(comment, cursor);
+        if (foundAt < 0) {
+            return false;
+        }
+        cursor = foundAt + 1;
+    }
+    return true;
+};
+const countCommandToken = (tokens, value) => {
+    return tokens.filter(token => token.type === TokenType.Command && token.value === value).length;
+};
+const applyRewriteEdits = (sql, edits) => {
+    return [...edits]
+        .sort((left, right) => right.start - left.start)
+        .reduce((current, edit) => {
+        return current.slice(0, edit.start) + edit.after + current.slice(edit.end);
+    }, sql);
+};
+const getStatementEndPosition = (sql) => {
+    let end = sql.length;
+    while (end > 0 && /\s/.test(sql[end - 1])) {
+        end--;
+    }
+    if (end > 0 && sql[end - 1] === ";") {
+        end--;
+        while (end > 0 && /\s/.test(sql[end - 1])) {
+            end--;
+        }
+    }
+    return end;
+};
+const clauseBoundaryCommands = new Set(["group by", "having", "order by", "limit", "offset", "fetch", "for"]);
+const isClauseBoundary = (lexeme) => {
+    return (lexeme.type & TokenType.Command) !== 0
+        && clauseBoundaryCommands.has(lexeme.value.toLowerCase());
+};
+const findMinimalWhereInsertPosition = (sql) => {
+    var _a, _b, _c, _d;
+    const lexemes = new SqlTokenizer(sql).tokenize();
+    const whereIndex = lexemes.findIndex(lexeme => (lexeme.type & TokenType.Command) !== 0 && lexeme.value.toLowerCase() === "where");
+    const statementEnd = getStatementEndPosition(sql);
+    if (whereIndex >= 0) {
+        const tail = lexemes.slice(whereIndex + 1).find(isClauseBoundary);
+        return {
+            position: (_b = (_a = tail === null || tail === void 0 ? void 0 : tail.position) === null || _a === void 0 ? void 0 : _a.startPosition) !== null && _b !== void 0 ? _b : statementEnd,
+            hasWhere: true
+        };
+    }
+    const tail = lexemes.find(isClauseBoundary);
+    return {
+        position: (_d = (_c = tail === null || tail === void 0 ? void 0 : tail.position) === null || _c === void 0 ? void 0 : _c.startPosition) !== null && _d !== void 0 ? _d : statementEnd,
+        hasWhere: false
+    };
+};
+const findMatchingParenEnd = (sql, start) => {
+    let depth = 0;
+    let quote = null;
+    for (let index = start; index < sql.length; index++) {
+        const char = sql[index];
+        if (quote) {
+            if (char === quote) {
+                if (quote === "'" && sql[index + 1] === "'") {
+                    index++;
+                    continue;
+                }
+                quote = null;
+            }
+            continue;
+        }
+        if (char === "'" || char === "\"") {
+            quote = char;
+            continue;
+        }
+        if (char === "(") {
+            depth++;
+        }
+        if (char === ")") {
+            depth--;
+            if (depth === 0) {
+                return index + 1;
+            }
+        }
+    }
+    return -1;
+};
+// Fallback for #854: findOptionalBranchSpans, findBooleanOperatorBefore, and
+// findBooleanOperatorAfter recover minimal remove spans until the AST can expose
+// source positions for optional parenthesized OR/IS NULL branches reliably.
+// Keep regex-based rewriting limited to this fallback path.
+const findOptionalBranchSpans = (sql, parameterName) => {
+    const spans = [];
+    const parameterNeedle = `:${parameterName.toLowerCase()}`;
+    const lowerSql = sql.toLowerCase();
+    for (let index = 0; index < sql.length; index++) {
+        if (sql[index] !== "(") {
+            continue;
+        }
+        const end = findMatchingParenEnd(sql, index);
+        if (end < 0) {
+            break;
+        }
+        const text = sql.slice(index, end);
+        const normalized = lowerSql.slice(index, end);
+        if (normalized.includes(parameterNeedle) && normalized.includes(" is null") && normalized.includes(" or ")) {
+            spans.push({ start: index, end, text });
+        }
+        index = end - 1;
+    }
+    return spans;
+};
+const findBooleanOperatorBefore = (sql, start) => {
+    const prefix = sql.slice(0, start);
+    const match = /(\s+)(and|or)(\s*)$/i.exec(prefix);
+    if (!match || match.index === undefined) {
+        return null;
+    }
+    return {
+        start: match.index,
+        end: start,
+        value: match[2].toLowerCase()
+    };
+};
+const findBooleanOperatorAfter = (sql, end) => {
+    const suffix = sql.slice(end);
+    const match = /^(\s*)(and|or)(\s+)/i.exec(suffix);
+    if (!match) {
+        return null;
+    }
+    return {
+        start: end,
+        end: end + match[0].length,
+        value: match[2].toLowerCase()
+    };
+};
+const findWhereBefore = (sql, position) => {
+    var _a, _b;
+    const lexemes = new SqlTokenizer(sql).tokenize();
+    let found = null;
+    for (const lexeme of lexemes) {
+        if (((_b = (_a = lexeme.position) === null || _a === void 0 ? void 0 : _a.startPosition) !== null && _b !== void 0 ? _b : 0) >= position) {
+            break;
+        }
+        if ((lexeme.type & TokenType.Command) !== 0 && lexeme.value.toLowerCase() === "where") {
+            found = lexeme;
+        }
+    }
+    if (!(found === null || found === void 0 ? void 0 : found.position)) {
+        return null;
+    }
+    return {
+        start: found.position.startPosition,
+        end: found.position.endPosition
+    };
+};
+const findSourceColumnReferenceText = (sql, reference) => {
+    const namespace = normalizeIdentifier(reference.getNamespace());
+    const column = normalizeIdentifier(reference.column.name);
+    const lexemes = new SqlTokenizer(sql).tokenize();
+    for (let index = 0; index < lexemes.length - 2; index++) {
+        const first = lexemes[index];
+        const dot = lexemes[index + 1];
+        const last = lexemes[index + 2];
+        if ((first.type & TokenType.Identifier) === 0 || dot.value !== "." || (last.type & TokenType.Identifier) === 0) {
+            continue;
+        }
+        if (normalizeIdentifier(first.value) !== namespace || normalizeIdentifier(last.value) !== column) {
+            continue;
+        }
+        if (!first.position || !last.position) {
+            continue;
+        }
+        return sql.slice(first.position.startPosition, last.position.endPosition);
+    }
+    return normalizeColumnReferenceText(reference);
+};
 const normalizeColumnReferenceKey = (reference) => {
     return `${normalizeIdentifier(reference.getNamespace())}.${normalizeIdentifier(reference.column.name)}`;
 };
@@ -358,6 +576,78 @@ export class SSSQLFilterBuilder {
         const parsed = this.parseQuery(query);
         return collectSupportedOptionalConditionBranches(parsed).map(getBranchInfo);
     }
+    planScaffold(query, filters) {
+        if (typeof query === "string") {
+            const entries = Object.entries(filters);
+            if (entries.length === 1) {
+                const [filterName, filterValue] = entries[0];
+                if (isExplicitEqualityScaffoldValue(filterValue)) {
+                    try {
+                        return this.planScalarInsert(query, {
+                            target: filterName,
+                            parameterName: makeParameterName(filterName),
+                            operator: "="
+                        });
+                    }
+                    catch (_a) {
+                        // Fall through to the conservative formatter-backed plan, which reports rewrite errors.
+                    }
+                }
+            }
+        }
+        return this.planRewrite(query, parsed => this.scaffold(parsed, filters));
+    }
+    dryRunScaffold(query, filters) {
+        return this.planScaffold(query, filters);
+    }
+    planScaffoldBranch(query, spec) {
+        if (typeof query === "string" && (spec.kind === "exists" || spec.kind === "not-exists")) {
+            try {
+                return this.planExistsInsert(query, spec);
+            }
+            catch (_a) {
+                // Fall through to the conservative formatter-backed plan, which reports rewrite errors.
+            }
+        }
+        if (typeof query === "string" && spec.kind !== "exists" && spec.kind !== "not-exists") {
+            try {
+                return this.planScalarInsert(query, spec);
+            }
+            catch (_b) {
+                // Fall through to the conservative formatter-backed plan, which reports rewrite errors.
+            }
+        }
+        return this.planRewrite(query, parsed => this.scaffoldBranch(parsed, spec));
+    }
+    dryRunScaffoldBranch(query, spec) {
+        return this.planScaffoldBranch(query, spec);
+    }
+    planRefresh(query, filters) {
+        return this.planRewrite(query, parsed => this.refresh(parsed, filters));
+    }
+    dryRunRefresh(query, filters) {
+        return this.planRefresh(query, filters);
+    }
+    planRemove(query, spec) {
+        if (typeof query === "string") {
+            try {
+                return this.planBranchRemoval(query, spec);
+            }
+            catch (_a) {
+                // Fall through to the conservative formatter-backed plan, which reports rewrite errors.
+            }
+        }
+        return this.planRewrite(query, parsed => this.remove(parsed, spec));
+    }
+    dryRunRemove(query, spec) {
+        return this.planRemove(query, spec);
+    }
+    planRemoveAll(query) {
+        return this.planRewrite(query, parsed => this.removeAll(parsed));
+    }
+    dryRunRemoveAll(query) {
+        return this.planRemoveAll(query);
+    }
     scaffold(query, filters) {
         const parsed = this.parseQuery(query);
         for (const [filterName, filterValue] of Object.entries(filters)) {
@@ -464,6 +754,383 @@ export class SSSQLFilterBuilder {
     parseQuery(query) {
         return typeof query === "string" ? SelectQueryParser.parse(query) : query;
     }
+    planScalarInsert(sourceSql, spec) {
+        var _a;
+        const parsed = SelectQueryParser.parse(sourceSql);
+        const target = this.resolveTarget(parsed, spec.target);
+        if (target.query !== parsed) {
+            return this.planRewrite(sourceSql, query => this.scaffoldBranch(query, spec));
+        }
+        const parameterName = ((_a = spec.parameterName) === null || _a === void 0 ? void 0 : _a.trim()) || target.parameterName;
+        const operator = normalizeScalarOperator(spec.operator);
+        const targetColumnText = findSourceColumnReferenceText(sourceSql, target.column);
+        const branchSql = `(:${parameterName} is null or ${targetColumnText} ${operator} :${parameterName})`;
+        const normalizedBranch = normalizeSql(branchSql);
+        const duplicate = this.list(parsed).find(existing => existing.query === target.query && normalizeSql(existing.sql) === normalizedBranch);
+        if (duplicate) {
+            return this.buildPlanFromEdits(sourceSql, [], [], []);
+        }
+        return this.buildMinimalInsertPlan(sourceSql, branchSql, {
+            branchKind: "scalar",
+            parameterName,
+            column: targetColumnText
+        });
+    }
+    planExistsInsert(sourceSql, spec) {
+        const parameterName = spec.parameterName.trim();
+        if (!parameterName) {
+            throw new Error("SSSQL EXISTS/NOT EXISTS scaffold requires parameterName.");
+        }
+        if (spec.anchorColumns.length === 0) {
+            throw new Error("SSSQL EXISTS/NOT EXISTS scaffold requires at least one anchorColumn.");
+        }
+        const parsed = SelectQueryParser.parse(sourceSql);
+        const anchorTargets = spec.anchorColumns.map(anchorColumn => this.resolveTarget(parsed, anchorColumn));
+        const targetQueries = [...new Set(anchorTargets.map(target => target.query))];
+        if (targetQueries.length !== 1) {
+            throw new Error("SSSQL EXISTS/NOT EXISTS scaffold anchor columns must resolve within one query scope.");
+        }
+        const targetQuery = targetQueries[0];
+        if (targetQuery !== parsed) {
+            return this.planRewrite(sourceSql, query => this.scaffoldBranch(query, spec));
+        }
+        const sourceColumns = anchorTargets.map(target => findSourceColumnReferenceText(sourceSql, target.column));
+        const substitutedSql = substituteAnchorPlaceholders(spec.query, sourceColumns).trim();
+        enforceSubqueryConstraints(substitutedSql);
+        const subquery = SelectQueryParser.parse(substitutedSql);
+        const parameterNames = new Set(ParameterCollector.collect(subquery).map(parameter => parameter.name.value));
+        if (parameterNames.size !== 1 || !parameterNames.has(parameterName)) {
+            throw new Error(`SSSQL ${spec.kind.toUpperCase()} scaffold query must reference only parameter ':${parameterName}'.`);
+        }
+        const branchSql = `(:${parameterName} is null or ${spec.kind === "not-exists" ? "not exists" : "exists"} (${substitutedSql}))`;
+        const duplicate = this.list(parsed).find(existing => existing.query === targetQuery && normalizeSql(existing.sql) === normalizeSql(branchSql));
+        if (duplicate) {
+            return this.buildPlanFromEdits(sourceSql, [], [], []);
+        }
+        return this.buildMinimalInsertPlan(sourceSql, branchSql, {
+            branchKind: spec.kind,
+            parameterName,
+            column: sourceColumns.join(", ")
+        });
+    }
+    buildMinimalInsertPlan(sourceSql, branchSql, target) {
+        const insertPosition = findMinimalWhereInsertPosition(sourceSql);
+        const needsLeadingSpace = insertPosition.position === 0
+            || !/\s/.test(sourceSql[insertPosition.position - 1]);
+        const prefix = `${needsLeadingSpace ? " " : ""}${insertPosition.hasWhere ? "and" : "where"} `;
+        const suffix = insertPosition.position < getStatementEndPosition(sourceSql) ? " " : "";
+        const branchLabel = target.branchKind === "scalar" ? "scalar" : target.branchKind;
+        const edit = {
+            start: insertPosition.position,
+            end: insertPosition.position,
+            before: "",
+            after: `${prefix}${branchSql}${suffix}`,
+            kind: "insert",
+            reason: insertPosition.hasWhere
+                ? `Append SSSQL ${branchLabel} branch to the existing WHERE clause.`
+                : `Create a WHERE clause for the SSSQL ${branchLabel} branch.`,
+            target
+        };
+        const changedRegions = [{
+                kind: "target-branch",
+                start: edit.start + prefix.length,
+                end: edit.start + edit.after.length - suffix.length,
+                message: `Inserted SSSQL ${branchLabel} optional branch.`
+            }];
+        if (insertPosition.hasWhere) {
+            changedRegions.unshift({
+                kind: "boolean-operator",
+                start: edit.start,
+                end: edit.start + prefix.length,
+                message: `Inserted AND before the SSSQL ${branchLabel} branch.`
+            });
+        }
+        else {
+            changedRegions.unshift({
+                kind: "where-keyword",
+                start: edit.start,
+                end: edit.start + prefix.length,
+                message: `Inserted WHERE before the SSSQL ${branchLabel} branch.`
+            });
+        }
+        return this.buildPlanFromEdits(sourceSql, [edit], changedRegions, []);
+    }
+    planBranchRemoval(sourceSql, spec) {
+        const parsed = SelectQueryParser.parse(sourceSql);
+        const matches = this.findMatchingBranchInfos(parsed, spec);
+        if (matches.length > 1) {
+            return this.buildPlanFromEdits(sourceSql, [], [], [], [{
+                    code: "REWRITE_FAILED",
+                    message: "SSSQL remove planning found multiple matching branches.",
+                    detail: `Multiple SSSQL branches matched parameter ':${spec.parameterName}'. Remove is ambiguous.`
+                }]);
+        }
+        if (matches.length === 0) {
+            return this.buildPlanFromEdits(sourceSql, [], [], []);
+        }
+        const branchSpans = findOptionalBranchSpans(sourceSql, spec.parameterName);
+        if (branchSpans.length > 1) {
+            return this.planRewrite(sourceSql, query => this.remove(query, spec));
+        }
+        const span = branchSpans[0];
+        if (!span) {
+            return this.planRewrite(sourceSql, query => this.remove(query, spec));
+        }
+        const beforeOperator = findBooleanOperatorBefore(sourceSql, span.start);
+        const afterOperator = findBooleanOperatorAfter(sourceSql, span.end);
+        const where = findWhereBefore(sourceSql, span.start);
+        let start = span.start;
+        let end = span.end;
+        const changedRegions = [{
+                kind: "target-branch",
+                start: span.start,
+                end: span.end,
+                message: "Removed SSSQL optional branch."
+            }];
+        if (beforeOperator) {
+            start = beforeOperator.start;
+            changedRegions.unshift({
+                kind: "boolean-operator",
+                start: beforeOperator.start,
+                end: beforeOperator.end,
+                message: `Removed adjacent ${beforeOperator.value.toUpperCase()} before the SSSQL branch.`
+            });
+        }
+        else if (afterOperator) {
+            end = afterOperator.end;
+            changedRegions.push({
+                kind: "boolean-operator",
+                start: afterOperator.start,
+                end: afterOperator.end,
+                message: `Removed adjacent ${afterOperator.value.toUpperCase()} after the SSSQL branch.`
+            });
+        }
+        else if (where) {
+            start = where.start;
+            while (end < sourceSql.length && /\s/.test(sourceSql[end])) {
+                end++;
+            }
+            changedRegions.unshift({
+                kind: "where-keyword",
+                start: where.start,
+                end: where.end,
+                message: "Removed WHERE because the SSSQL branch was the only condition."
+            });
+        }
+        const edit = {
+            start,
+            end,
+            before: sourceSql.slice(start, end),
+            after: "",
+            kind: "delete",
+            reason: "Remove the targeted SSSQL optional branch from the source SQL.",
+            target: {
+                branchKind: matches[0].kind,
+                parameterName: matches[0].parameterName,
+                column: matches[0].target
+            }
+        };
+        return this.buildPlanFromEdits(sourceSql, [edit], changedRegions, []);
+    }
+    buildPlanFromEdits(sourceSql, edits, changedRegions, warnings, errors = []) {
+        const plannedSql = errors.length === 0 ? applyRewriteEdits(sourceSql, edits) : undefined;
+        const beforeTokens = tokenizeForRewritePlan(sourceSql);
+        const beforeComments = collectCommentFragments(sourceSql);
+        const afterTokens = plannedSql !== undefined ? tokenizeForRewritePlan(plannedSql) : [];
+        const afterComments = plannedSql !== undefined ? collectCommentFragments(plannedSql) : [];
+        const commentsPreserved = plannedSql !== undefined
+            ? commentsPreservedInOrder(beforeComments, afterComments)
+            : false;
+        const changedOnlyTargetBranches = errors.length === 0
+            && changedRegions.every(region => region.kind === "target-branch"
+                || region.kind === "where-keyword"
+                || region.kind === "boolean-operator"
+                || region.kind === "parentheses")
+            && commentsPreserved;
+        const planWarnings = [...warnings];
+        if (plannedSql !== undefined && applyRewriteEdits(sourceSql, edits) !== plannedSql) {
+            errors = [...errors, {
+                    code: "APPLY_PLAN_MISMATCH",
+                    message: "Applying SSSQL rewrite plan edits did not reproduce the planned SQL."
+                }];
+        }
+        if (plannedSql !== undefined) {
+            try {
+                SelectQueryParser.parse(plannedSql);
+            }
+            catch (error) {
+                errors = [...errors, {
+                        code: "PARSE_AFTER_FAILED",
+                        message: "The SQL produced by SSSQL rewrite planning could not be parsed.",
+                        detail: error instanceof Error ? error.message : error
+                    }];
+            }
+        }
+        if (plannedSql !== undefined && !commentsPreserved) {
+            planWarnings.push({
+                code: "COMMENTS_NOT_PRESERVED",
+                message: "One or more input SQL comments are missing or reordered after the SSSQL rewrite."
+            });
+        }
+        return {
+            ok: errors.length === 0,
+            requiresFullReformat: false,
+            edits,
+            sql: plannedSql,
+            safety: {
+                tokenCountBefore: beforeTokens.length,
+                tokenCountAfter: afterTokens.length,
+                tokenSequencePreserved: plannedSql !== undefined ? tokenSequencesEqual(beforeTokens, afterTokens) : false,
+                commentsPreserved,
+                changedOnlyTargetBranches,
+                changedRegions
+            },
+            warnings: planWarnings,
+            errors
+        };
+    }
+    planRewrite(query, rewrite) {
+        const warnings = [];
+        const errors = [];
+        const sourceSql = typeof query === "string"
+            ? query
+            : formatSqlComponent(query);
+        if (typeof query !== "string") {
+            warnings.push({
+                code: "SOURCE_SQL_UNAVAILABLE",
+                message: "SSSQL rewrite planning received an AST, so the source SQL had to be formatter-generated before analysis."
+            });
+        }
+        let beforeTokens = [];
+        let beforeComments = [];
+        try {
+            beforeTokens = tokenizeForRewritePlan(sourceSql);
+            beforeComments = collectCommentFragments(sourceSql);
+        }
+        catch (error) {
+            errors.push({
+                code: "TOKENIZE_BEFORE_FAILED",
+                message: "Could not tokenize the input SQL before SSSQL rewrite planning.",
+                detail: error instanceof Error ? error.message : error
+            });
+        }
+        let plannedSql;
+        let afterTokens = [];
+        let afterComments = [];
+        if (errors.length === 0) {
+            try {
+                const parsed = SelectQueryParser.parse(sourceSql);
+                const rewritten = rewrite(parsed);
+                plannedSql = formatSqlComponent(rewritten);
+            }
+            catch (error) {
+                errors.push({
+                    code: "REWRITE_FAILED",
+                    message: "SSSQL rewrite planning could not produce a rewritten query.",
+                    detail: error instanceof Error ? error.message : error
+                });
+            }
+        }
+        if (plannedSql !== undefined) {
+            try {
+                SelectQueryParser.parse(plannedSql);
+            }
+            catch (error) {
+                errors.push({
+                    code: "PARSE_AFTER_FAILED",
+                    message: "The SQL produced by SSSQL rewrite planning could not be parsed.",
+                    detail: error instanceof Error ? error.message : error
+                });
+            }
+            try {
+                afterTokens = tokenizeForRewritePlan(plannedSql);
+                afterComments = collectCommentFragments(plannedSql);
+            }
+            catch (error) {
+                errors.push({
+                    code: "TOKENIZE_AFTER_FAILED",
+                    message: "Could not tokenize the SQL produced by SSSQL rewrite planning.",
+                    detail: error instanceof Error ? error.message : error
+                });
+            }
+        }
+        const edits = plannedSql !== undefined && plannedSql !== sourceSql
+            ? [{
+                    start: 0,
+                    end: sourceSql.length,
+                    before: sourceSql,
+                    after: plannedSql,
+                    kind: "replace",
+                    reason: "Current SSSQL rewrite planning is backed by AST rewrite plus formatter output."
+                }]
+            : [];
+        const changedRegions = edits.length > 0
+            ? [{
+                    kind: "formatter-rewrite",
+                    start: 0,
+                    end: sourceSql.length,
+                    message: "The conservative SSSQL rewrite plan requires replacing formatter output for the full SQL text."
+                }]
+            : [];
+        const requiresFullReformat = edits.length > 0;
+        const tokenSequencePreserved = plannedSql !== undefined
+            ? tokenSequencesEqual(beforeTokens, afterTokens)
+            : false;
+        const commentsPreserved = plannedSql !== undefined
+            ? commentsPreservedInOrder(beforeComments, afterComments)
+            : false;
+        const changedOnlyTargetBranches = edits.length === 0;
+        if (requiresFullReformat) {
+            warnings.push({
+                code: "FULL_REFORMAT_REQUIRED",
+                message: "The current SSSQL rewrite plan can only represent the change as a full SQL replacement."
+            });
+        }
+        if (plannedSql !== undefined && !tokenSequencePreserved) {
+            warnings.push({
+                code: "TOKEN_SEQUENCE_CHANGED",
+                message: "The SQL token sequence changes after the SSSQL rewrite. The conservative planner cannot prove that only target branches changed.",
+                detail: {
+                    tokenCountBefore: beforeTokens.length,
+                    tokenCountAfter: afterTokens.length
+                }
+            });
+        }
+        if (plannedSql !== undefined && !commentsPreserved) {
+            warnings.push({
+                code: "COMMENTS_NOT_PRESERVED",
+                message: "One or more input SQL comments are missing or reordered after the SSSQL rewrite."
+            });
+        }
+        if (plannedSql !== undefined && countCommandToken(afterTokens, "as") > countCommandToken(beforeTokens, "as")) {
+            warnings.push({
+                code: "OPTIONAL_ALIAS_AS_ADDED",
+                message: "The rewrite output contains more AS tokens than the input, which may indicate formatter-added aliases."
+            });
+        }
+        if (plannedSql !== undefined && !sourceSql.includes("\"") && plannedSql.includes("\"")) {
+            warnings.push({
+                code: "IDENTIFIER_QUOTES_ADDED",
+                message: "The rewrite output contains double-quoted identifiers that were not present in the input SQL."
+            });
+        }
+        return {
+            ok: errors.length === 0,
+            requiresFullReformat,
+            edits,
+            sql: plannedSql,
+            safety: {
+                tokenCountBefore: beforeTokens.length,
+                tokenCountAfter: afterTokens.length,
+                tokenSequencePreserved,
+                commentsPreserved,
+                changedOnlyTargetBranches,
+                changedRegions
+            },
+            warnings,
+            errors
+        };
+    }
     findMatchingBranchInfos(root, spec) {
         const normalizedOperator = spec.operator ? normalizeScalarOperator(spec.operator) : undefined;
         const normalizedTarget = spec.target ? normalizeIdentifier(spec.target) : undefined;