@rawsql-ts/ztd-cli 0.20.0 → 0.20.2

package/dist/query/location.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearStatementCache = clearStatementCache;
+exports.locateUsageText = locateUsageText;
+const MAX_SNIPPET_LENGTH = 200;
+const MAX_STATEMENT_CACHE_SIZE = 256;
+const statementCache = new Map();
+function clearStatementCache() {
+    statementCache.clear();
+}
+/**
+ * Locate the best matching occurrence in a statement and project it to file-relative coordinates.
+ */
+function locateUsageText(params) {
+    const cache = getStatementCache(params.statementText);
+    const occurrences = collectOccurrences(params.statementText, params.candidates);
+    if (occurrences.length === 0) {
+        return {
+            location: null,
+            snippet: params.statementText.trim(),
+            ambiguous: false
+        };
+    }
+    const clauseWindow = params.clauseAnchor
+        ? findClauseWindow(cache, params.clauseAnchor)
+        : null;
+    const selected = selectOccurrence(occurrences, clauseWindow);
+    if (!selected) {
+        return {
+            location: null,
+            snippet: extractSnippet(params.statementText, 0, Math.min(params.statementText.length, MAX_SNIPPET_LENGTH)),
+            ambiguous: occurrences.length > 1
+        };
+    }
+    const snippet = params.snippetMode === 'line'
+        ? extractLineSnippet(params.statementText, selected.start, selected.end)
+        : extractClauseSnippet(params.statementText, selected.start, selected.end, clauseWindow);
+    return {
+        location: buildLocation(params.statementText, params.statementStartOffsetInFile, selected.start, selected.end),
+        snippet,
+        ambiguous: selected.ambiguous
+    };
+}
+function getStatementCache(statementText) {
+    const cached = statementCache.get(statementText);
+    if (cached) {
+        // Refresh cache recency on access so older statements are evicted first.
+        statementCache.delete(statementText);
+        statementCache.set(statementText, cached);
+        return cached;
+    }
+    const clauseMarkers = Array.from(statementText.matchAll(/\b(WHERE|ORDER\s+BY|GROUP\s+BY|HAVING|RETURNING|SET|JOIN|ON|USING|FROM|INSERT\s+INTO|UPDATE|DELETE\s+FROM)\b/gi))
+        .map((match) => {
+        var _a, _b;
+        return ({
+            start: (_a = match.index) !== null && _a !== void 0 ? _a : 0,
+            end: ((_b = match.index) !== null && _b !== void 0 ? _b : 0) + match[0].length,
+            keyword: match[0].toUpperCase()
+        });
+    })
+        .sort((left, right) => left.start - right.start || left.end - right.end);
+    const value = { clauseMarkers };
+    setStatementCache(statementText, value);
+    return value;
+}
+function setStatementCache(statementText, value) {
+    if (statementCache.has(statementText)) {
+        statementCache.delete(statementText);
+    }
+    statementCache.set(statementText, value);
+    // Keep the cache bounded for long-running CLI processes and large batch scans.
+    while (statementCache.size > MAX_STATEMENT_CACHE_SIZE) {
+        const oldestKey = statementCache.keys().next().value;
+        if (oldestKey === undefined) {
+            break;
+        }
+        statementCache.delete(oldestKey);
+    }
+}
+function selectOccurrence(occurrences, clauseWindow) {
+    if (!clauseWindow) {
+        return occurrences.length > 0
+            ? {
+                ...occurrences[0],
+                ambiguous: occurrences.length > 1
+            }
+            : null;
+    }
+    const inWindow = occurrences.filter((occurrence) => occurrence.start >= clauseWindow.start &&
+        occurrence.start < clauseWindow.end);
+    const candidates = inWindow.length > 0
+        ? inWindow
+        : occurrences.filter((occurrence) => occurrence.start >= clauseWindow.start);
+    const selectedPool = candidates.length > 0 ? candidates : occurrences;
+    if (selectedPool.length === 0) {
+        return null;
+    }
+    const selected = [...selectedPool].sort((left, right) => Math.abs(left.start - clauseWindow.start) - Math.abs(right.start - clauseWindow.start) ||
+        left.start - right.start ||
+        (right.end - right.start) - (left.end - left.start))[0];
+    return {
+        ...selected,
+        ambiguous: selectedPool.length > 1
+    };
+}
+function findClauseWindow(cache, clauseAnchor) {
+    var _a;
+    const anchorPattern = clauseAnchor.tokens.join(' ').toUpperCase();
+    const anchor = cache.clauseMarkers.find((marker) => marker.keyword === anchorPattern);
+    if (!anchor) {
+        return null;
+    }
+    const nextClause = cache.clauseMarkers.find((marker) => marker.start > anchor.end);
+    return {
+        anchorStart: anchor.start,
+        start: anchor.end,
+        end: (_a = nextClause === null || nextClause === void 0 ? void 0 : nextClause.start) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER
+    };
+}
+function collectOccurrences(statementText, candidates) {
+    var _a;
+    const occurrences = [];
+    for (const candidate of Array.from(new Set(candidates.filter(Boolean)))) {
+        const pattern = buildCandidatePattern(candidate);
+        for (const match of statementText.matchAll(pattern)) {
+            const start = (_a = match.index) !== null && _a !== void 0 ? _a : -1;
+            if (start < 0) {
+                continue;
+            }
+            occurrences.push({
+                start,
+                end: start + match[0].length
+            });
+        }
+    }
+    return dedupeOccurrences(occurrences);
+}
+function buildCandidatePattern(candidate) {
+    const parts = candidate.split('.');
+    const pattern = parts
+        .map((part) => `(?:"${escapeRegex(part)}"|${escapeRegex(part)})`)
+        .join('\\s*\\.\\s*');
+    return new RegExp(`(?<![A-Za-z0-9_])${pattern}(?![A-Za-z0-9_])`, 'gi');
+}
+function dedupeOccurrences(occurrences) {
+    const sorted = [...occurrences].sort((left, right) => left.start - right.start ||
+        (right.end - right.start) - (left.end - left.start) ||
+        left.end - right.end);
+    const deduped = [];
+    for (const occurrence of sorted) {
+        const duplicate = deduped.find((entry) => (entry.start === occurrence.start && entry.end === occurrence.end) ||
+            (occurrence.start >= entry.start && occurrence.end <= entry.end));
+        if (!duplicate) {
+            deduped.push(occurrence);
+        }
+    }
+    return deduped.sort((left, right) => left.start - right.start ||
+        (right.end - right.start) - (left.end - left.start));
+}
+function clampSnippetEnd(selectedEnd, clauseEnd) {
+    return Math.min(Math.max(selectedEnd, 0) + MAX_SNIPPET_LENGTH, clauseEnd);
+}
+function extractClauseSnippet(statementText, selectedStart, selectedEnd, clauseWindow) {
+    var _a;
+    const snippetStart = clauseWindow ? clauseWindow.anchorStart : selectedStart;
+    const snippetEnd = clampSnippetEnd(selectedEnd, (_a = clauseWindow === null || clauseWindow === void 0 ? void 0 : clauseWindow.end) !== null && _a !== void 0 ? _a : statementText.length);
+    return extractSnippet(statementText, snippetStart, snippetEnd);
+}
+function extractLineSnippet(statementText, start, end) {
+    // Keep table snippets anchored to the concrete identifier line so the reason for the match is obvious.
+    const lineStart = statementText.lastIndexOf('\n', Math.max(0, start - 1)) + 1;
+    const lineEndIndex = statementText.indexOf('\n', end);
+    const lineEnd = lineEndIndex >= 0 ? lineEndIndex : statementText.length;
+    return extractSnippet(statementText, lineStart, lineEnd);
+}
+function buildLocation(statementText, statementStartOffsetInFile, statementOffsetStart, statementOffsetEnd) {
+    const start = offsetToLineColumn(statementText, statementOffsetStart);
+    const end = offsetToLineColumn(statementText, statementOffsetEnd);
+    return {
+        startLine: start.line,
+        startColumn: start.column,
+        endLine: end.line,
+        endColumn: end.column,
+        fileOffsetStart: statementStartOffsetInFile + statementOffsetStart,
+        fileOffsetEnd: statementStartOffsetInFile + statementOffsetEnd,
+        statementOffsetStart,
+        statementOffsetEnd
+    };
+}
+function extractSnippet(statementText, start, end) {
+    return statementText.slice(Math.max(0, start), Math.min(end, statementText.length)).trim();
+}
+function offsetToLineColumn(text, offset) {
+    const safeOffset = Math.max(0, Math.min(offset, text.length));
+    const lines = text.slice(0, safeOffset).split('\n');
+    return {
+        line: lines.length,
+        column: lines[lines.length - 1].length + 1
+    };
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=location.js.map

package/dist/query/location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location.js","sourceRoot":"","sources":["../../src/query/location.ts"],"names":[],"mappings":"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"}

package/dist/query/patch.d.ts

@@ -0,0 +1,21 @@
+export interface QueryPatchApplyOptions {
+    cte: string;
+    from: string;
+    out?: string;
+    preview?: boolean;
+}
+export interface QueryPatchApplyReport {
+    file: string;
+    edited_file: string;
+    target_cte: string;
+    preview: boolean;
+    changed: boolean;
+    written: boolean;
+    output_file: string;
+    updated_sql: string;
+    diff: string;
+}
+/**
+ * Replace one CTE in the original SQL with the matching edited CTE definition.
+ */
+export declare function applyQueryPatch(sqlFile: string, options: QueryPatchApplyOptions): QueryPatchApplyReport;

package/dist/query/patch.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyQueryPatch = applyQueryPatch;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const diff_1 = require("diff");
+const rawsql_ts_1 = require("rawsql-ts");
+const fs_1 = require("../utils/fs");
+const analysis_1 = require("./analysis");
+/**
+ * Replace one CTE in the original SQL with the matching edited CTE definition.
+ */
+function applyQueryPatch(sqlFile, options) {
+    var _a;
+    const targetCte = normalizeTargetCte(options.cte);
+    const absoluteOriginalPath = node_path_1.default.resolve(sqlFile);
+    const absoluteEditedPath = node_path_1.default.resolve(options.from);
+    const outputFile = node_path_1.default.resolve((_a = options.out) !== null && _a !== void 0 ? _a : absoluteOriginalPath);
+    const originalSql = (0, node_fs_1.readFileSync)(absoluteOriginalPath, 'utf8');
+    const editedSql = (0, node_fs_1.readFileSync)(absoluteEditedPath, 'utf8');
+    const originalStatement = (0, analysis_1.assertSupportedStatement)(rawsql_ts_1.SqlParser.parse(originalSql), 'ztd query patch apply');
+    const originalWithClause = requireWithClause(originalStatement, absoluteOriginalPath);
+    const replacement = extractReplacementCte(editedSql, targetCte, absoluteEditedPath);
+    const targetIndex = findExactlyOneCteIndex(originalWithClause, targetCte, absoluteOriginalPath);
+    // Replace only the requested CTE while preserving the original WITH clause order.
+    originalWithClause.tables.splice(targetIndex, 1, replacement);
+    const formatter = new rawsql_ts_1.SqlFormatter();
+    const updatedSql = `${formatter.format(originalStatement).formattedSql}\n`;
+    // Re-parse the emitted SQL so syntax errors fail before any file write happens.
+    (0, analysis_1.assertSupportedStatement)(rawsql_ts_1.SqlParser.parse(updatedSql), 'ztd query patch apply');
+    const diff = createPatch(absoluteOriginalPath, outputFile, originalSql, updatedSql);
+    const changed = normalizeLineEndings(originalSql) !== normalizeLineEndings(updatedSql);
+    const preview = Boolean(options.preview);
+    if (!preview) {
+        (0, fs_1.ensureDirectory)(node_path_1.default.dirname(outputFile));
+        (0, node_fs_1.writeFileSync)(outputFile, updatedSql, 'utf8');
+    }
+    return {
+        file: absoluteOriginalPath,
+        edited_file: absoluteEditedPath,
+        target_cte: targetCte,
+        preview,
+        changed,
+        written: !preview,
+        output_file: outputFile,
+        updated_sql: updatedSql,
+        diff
+    };
+}
+function normalizeTargetCte(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error('ztd query patch apply requires --cte <name>.');
+    }
+    return normalized;
+}
+function extractReplacementCte(sql, targetCte, sourceFile) {
+    try {
+        const parsed = (0, analysis_1.assertSupportedStatement)(rawsql_ts_1.SqlParser.parse(sql), 'ztd query patch apply');
+        return extractReplacementCteFromStatement(parsed, targetCte, sourceFile);
+    }
+    catch (statementError) {
+        try {
+            const snippet = sql.trim().replace(/;\s*$/, '');
+            const parsed = (0, analysis_1.assertSupportedStatement)(rawsql_ts_1.SqlParser.parse(`with ${snippet} select 1`), 'ztd query patch apply');
+            return extractReplacementCteFromStatement(parsed, targetCte, sourceFile);
+        }
+        catch {
+            throw statementError;
+        }
+    }
+}
+function extractReplacementCteFromStatement(statement, targetCte, sourceFile) {
+    const withClause = getWithClause(statement);
+    if (!withClause) {
+        throw new Error(`Edited SQL must include the target CTE "${targetCte}" in a WITH clause.`);
+    }
+    const targetIndex = findExactlyOneCteIndex(withClause, targetCte, sourceFile);
+    return withClause.tables[targetIndex];
+}
+function requireWithClause(statement, sourceFile) {
+    const withClause = getWithClause(statement);
+    if (!withClause) {
+        throw new Error(`SQL file does not contain a WITH clause: ${sourceFile}`);
+    }
+    return withClause;
+}
+function findExactlyOneCteIndex(withClause, targetCte, sourceFile) {
+    const matches = withClause.tables
+        .map((cte, index) => ({ cte, index }))
+        .filter((entry) => entry.cte.aliasExpression.table.name.toLowerCase() === targetCte.toLowerCase());
+    if (matches.length === 0) {
+        throw new Error(`CTE "${targetCte}" was not found in ${sourceFile}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`CTE "${targetCte}" appears multiple times in ${sourceFile}; patch apply requires a unique target.`);
+    }
+    return matches[0].index;
+}
+function createPatch(originalFile, outputFile, before, after) {
+    return (0, diff_1.createTwoFilesPatch)(normalizePath(originalFile), normalizePath(outputFile), normalizeLineEndings(before), normalizeLineEndings(after), '', '', { context: 3 });
+}
+function normalizeLineEndings(value) {
+    return value.replace(/\r\n/g, '\n');
+}
+function normalizePath(value) {
+    return value.split(node_path_1.default.sep).join('/');
+}
+function getWithClause(statement) {
+    var _a;
+    if (statement instanceof rawsql_ts_1.SimpleSelectQuery ||
+        statement instanceof rawsql_ts_1.ValuesQuery ||
+        statement instanceof rawsql_ts_1.UpdateQuery ||
+        statement instanceof rawsql_ts_1.DeleteQuery) {
+        return (_a = statement.withClause) !== null && _a !== void 0 ? _a : null;
+    }
+    if (statement instanceof rawsql_ts_1.InsertQuery) {
+        return statement.selectQuery ? getSelectWithClause(assertSelectStatement(statement.selectQuery)) : null;
+    }
+    return getSelectWithClause(statement);
+}
+function getSelectWithClause(statement) {
+    var _a, _b;
+    if (statement instanceof rawsql_ts_1.SimpleSelectQuery || statement instanceof rawsql_ts_1.ValuesQuery) {
+        return (_a = statement.withClause) !== null && _a !== void 0 ? _a : null;
+    }
+    let current = statement;
+    while (current instanceof rawsql_ts_1.BinarySelectQuery) {
+        if (current.left instanceof rawsql_ts_1.BinarySelectQuery) {
+            current = current.left;
+            continue;
+        }
+        if (current.left instanceof rawsql_ts_1.SimpleSelectQuery || current.left instanceof rawsql_ts_1.ValuesQuery) {
+            return (_b = current.left.withClause) !== null && _b !== void 0 ? _b : null;
+        }
+        break;
+    }
+    return null;
+}
+function assertSelectStatement(statement) {
+    if (statement instanceof rawsql_ts_1.SimpleSelectQuery ||
+        statement instanceof rawsql_ts_1.BinarySelectQuery ||
+        statement instanceof rawsql_ts_1.ValuesQuery) {
+        return statement;
+    }
+    throw new Error('Expected a SELECT-compatible statement.');
+}
+//# sourceMappingURL=patch.js.map

package/dist/query/patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.js","sourceRoot":"","sources":["../../src/query/patch.ts"],"names":[],"mappings":";;;;;AAwCA,0CA+CC;AAvFD,qCAAsD;AACtD,0DAA6B;AAC7B,+BAA2C;AAC3C,yCAWmB;AACnB,oCAA8C;AAC9C,yCAA+E;AAqB/E;;GAEG;AACH,SAAgB,eAAe,CAAC,OAAe,EAAE,OAA+B;;IAC9E,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,oBAAoB,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,kBAAkB,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,mBAAI,CAAC,OAAO,CAAC,MAAA,OAAO,CAAC,GAAG,mCAAI,oBAAoB,CAAC,CAAC;IACrE,MAAM,WAAW,GAAG,IAAA,sBAAY,EAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAA,sBAAY,EAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAE3D,MAAM,iBAAiB,GAAG,IAAA,mCAAwB,EAAC,qBAAS,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAC1G,MAAM,kBAAkB,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC;IACtF,MAAM,WAAW,GAAG,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACpF,MAAM,WAAW,GAAG,sBAAsB,CAAC,kBAAkB,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;IAEhG,kFAAkF;IAClF,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;IAE9D,MAAM,SAAS,GAAG,IAAI,wBAAY,EAAE,CAAC;IACrC,MAAM,UAAU,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,YAAY,IAAI,CAAC;IAE3E,gFAAgF;IAChF,IAAA,mCAAwB,EAAC,qBAAS,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC,CAAC;IAE/E,MAAM,IAAI,GAAG,WAAW,CACtB,oBAAoB,EACpB,UAAU,EACV,WAAW,EACX,UAAU,CACX,CAAC;IACF,MAAM,OAAO,GAAG,oBAAoB,CAAC,WAAW,CAAC,KAAK,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,IAAA,oBAAe,EAAC,mBAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;QAC1C,IAAA,uBAAa,EAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IAED,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,kBAAkB;QAC/B,UAAU,EAAE,SAAS;QACrB,OAAO;QACP,OAAO;QACP,OAAO,EAAE,CAAC,OAAO;QACjB,WAAW,EAAE,UAAU;QACvB,WAAW,EAAE,UAAU;QACvB,IAAI;KACL,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAW,EAAE,SAAiB,EAAE,UAAkB;IAC/E,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,mCAAwB,EAAC,qBAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,uBAAuB,CAAC,CAAC;QACvF,OAAO,kCAAkC,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC3E,CAAC;IAAC,OAAO,cAAc,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAChD,MAAM,MAAM,GAAG,IAAA,mCAAwB,EAAC,qBAAS,CAAC,KAAK,CAAC,QAAQ,OAAO,WAAW,CAAC,EAAE,uBAAuB,CAAC,CAAC;YAC9G,OAAO,kCAAkC,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QAC3E,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,cAAc,CAAC;QACvB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,kCAAkC,CAAC,SAA6B,EAAE,SAAiB,EAAE,UAAkB;IAC9G,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,2CAA2C,SAAS,qBAAqB,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,WAAW,GAAG,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC9E,OAAO,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,iBAAiB,CAAC,SAA6B,EAAE,UAAkB;IAC1E,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,4CAA4C,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,sBAAsB,CAAC,UAAsB,EAAE,SAAiB,EAAE,UAAkB;IAC3F,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM;SAC9B,GAAG,CAAC,CAAC,GAAgB,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;SAC1D,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC;IAErG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,QAAQ,SAAS,sBAAsB,UAAU,GAAG,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,QAAQ,SAAS,+BAA+B,UAAU,yCAAyC,CAAC,CAAC;IACvH,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC1B,CAAC;AAED,SAAS,WAAW,CAAC,YAAoB,EAAE,UAAkB,EAAE,MAAc,EAAE,KAAa;IAC1F,OAAO,IAAA,0BAAmB,EACxB,aAAa,CAAC,YAAY,CAAC,EAC3B,aAAa,CAAC,UAAU,CAAC,EACzB,oBAAoB,CAAC,MAAM,CAAC,EAC5B,oBAAoB,CAAC,KAAK,CAAC,EAC3B,EAAE,EACF,EAAE,EACF,EAAE,OAAO,EAAE,CAAC,EAAE,CACf,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,mBAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,aAAa,CAAC,SAA6B;;IAClD,IACE,SAAS,YAAY,6BAAiB;QACtC,SAAS,YAAY,uBAAW;QAChC,SAAS,YAAY,uBAAW;QAChC,SAAS,YAAY,uBAAW,EAChC,CAAC;QACD,OAAO,MAAA,SAAS,CAAC,UAAU,mCAAI,IAAI,CAAC;IACtC,CAAC;IAED,IAAI,SAAS,YAAY,uBAAW,EAAE,CAAC;QACrC,OAAO,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1G,CAAC;IAED,OAAO,mBAAmB,CAAC,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,mBAAmB,CAAC,SAA8D;;IACzF,IAAI,SAAS,YAAY,6BAAiB,IAAI,SAAS,YAAY,uBAAW,EAAE,CAAC;QAC/E,OAAO,MAAA,SAAS,CAAC,UAAU,mCAAI,IAAI,CAAC;IACtC,CAAC;IAED,IAAI,OAAO,GAAwD,SAAS,CAAC;IAC7E,OAAO,OAAO,YAAY,6BAAiB,EAAE,CAAC;QAC5C,IAAI,OAAO,CAAC,IAAI,YAAY,6BAAiB,EAAE,CAAC;YAC9C,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;YACvB,SAAS;QACX,CAAC;QAED,IAAI,OAAO,CAAC,IAAI,YAAY,6BAAiB,IAAI,OAAO,CAAC,IAAI,YAAY,uBAAW,EAAE,CAAC;YACrF,OAAO,MAAA,OAAO,CAAC,IAAI,CAAC,UAAU,mCAAI,IAAI,CAAC;QACzC,CAAC;QAED,MAAM;IACR,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,qBAAqB,CAAC,SAAkB;IAC/C,IACE,SAAS,YAAY,6BAAiB;QACtC,SAAS,YAAY,6BAAiB;QACtC,SAAS,YAAY,uBAAW,EAChC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/query/planner.d.ts

@@ -0,0 +1,31 @@
+import { type QueryStructureReport } from './structure';
+export type QueryPipelinePlanFormat = 'text' | 'json';
+export type QueryPipelineStepKind = 'materialize' | 'final-query';
+export interface QueryPipelineMetadata {
+    material?: string[];
+    scalarFilterColumns?: string[];
+}
+export interface QueryPipelineStep {
+    step: number;
+    kind: QueryPipelineStepKind;
+    target: string;
+    depends_on: string[];
+}
+export interface QueryPipelinePlan {
+    file: string;
+    query_type: QueryStructureReport['query_type'];
+    final_query: string | null;
+    metadata: {
+        material: string[];
+        scalarFilterColumns: string[];
+    };
+    steps: QueryPipelineStep[];
+}
+/**
+ * Build a deterministic execution plan from query structure and runtime metadata.
+ */
+export declare function buildQueryPipelinePlan(sqlFile: string, metadata?: QueryPipelineMetadata): QueryPipelinePlan;
+/**
+ * Render the pipeline plan for machine or human consumption.
+ */
+export declare function formatQueryPipelinePlan(plan: QueryPipelinePlan, format: QueryPipelinePlanFormat): string;

package/dist/query/planner.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildQueryPipelinePlan = buildQueryPipelinePlan;
+exports.formatQueryPipelinePlan = formatQueryPipelinePlan;
+const structure_1 = require("./structure");
+/**
+ * Build a deterministic execution plan from query structure and runtime metadata.
+ */
+function buildQueryPipelinePlan(sqlFile, metadata = {}) {
+    var _a, _b;
+    const report = (0, structure_1.buildQueryStructureReport)(sqlFile);
+    const material = uniquePreservingOrder((_a = metadata.material) !== null && _a !== void 0 ? _a : []);
+    const scalarFilterColumns = uniquePreservingOrder((_b = metadata.scalarFilterColumns) !== null && _b !== void 0 ? _b : []);
+    const cteNameSet = new Set(report.ctes.map((cte) => cte.name));
+    validateKnownCtes(material, cteNameSet, 'material');
+    const orderedCtes = topologicallySortCtes(report);
+    const plannedCtes = orderedCtes.filter((name) => material.includes(name));
+    const cteMap = new Map(report.ctes.map((cte) => [cte.name, cte]));
+    const steps = plannedCtes.map((name, index) => {
+        var _a, _b;
+        return ({
+            step: index + 1,
+            kind: 'materialize',
+            target: name,
+            depends_on: [...((_b = (_a = cteMap.get(name)) === null || _a === void 0 ? void 0 : _a.depends_on) !== null && _b !== void 0 ? _b : [])]
+        });
+    });
+    steps.push({
+        step: steps.length + 1,
+        kind: 'final-query',
+        target: 'FINAL_QUERY',
+        depends_on: resolveFinalQueryDependencies(report, cteNameSet)
+    });
+    return {
+        file: report.file,
+        query_type: report.query_type,
+        final_query: report.final_query,
+        metadata: {
+            material,
+            scalarFilterColumns
+        },
+        steps
+    };
+}
+/**
+ * Render the pipeline plan for machine or human consumption.
+ */
+function formatQueryPipelinePlan(plan, format) {
+    if (format === 'json') {
+        return `${JSON.stringify(plan, null, 2)}\n`;
+    }
+    return `${formatQueryPipelineText(plan)}\n`;
+}
+function formatQueryPipelineText(plan) {
+    const lines = [
+        `Query type: ${plan.query_type}`,
+        `Material CTEs: ${plan.metadata.material.length > 0 ? plan.metadata.material.join(', ') : '(none)'}`,
+        `Scalar filter columns: ${plan.metadata.scalarFilterColumns.length > 0 ? plan.metadata.scalarFilterColumns.join(', ') : '(none)'}`,
+        '',
+        'Planned steps:'
+    ];
+    for (const step of plan.steps) {
+        lines.push(`${step.step}. ${describeStep(step)}`);
+        lines.push(`   depends_on: ${step.depends_on.length > 0 ? step.depends_on.join(', ') : '(none)'}`);
+    }
+    return lines.join('\n');
+}
+function describeStep(step) {
+    switch (step.kind) {
+        case 'materialize':
+            return `materialize ${step.target}`;
+        case 'final-query':
+        default:
+            return 'run final query';
+    }
+}
+function validateKnownCtes(names, cteNameSet, label) {
+    for (const name of names) {
+        if (!cteNameSet.has(name)) {
+            throw new Error(`Unknown ${label} CTE: ${name}`);
+        }
+    }
+}
+function resolveFinalQueryDependencies(report, cteNameSet) {
+    if (!report.final_query) {
+        return [];
+    }
+    return report.final_query
+        .split(',')
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0 && cteNameSet.has(value));
+}
+function topologicallySortCtes(report) {
+    const cteMap = new Map(report.ctes.map((cte) => [cte.name, cte]));
+    const cteOrder = new Map(report.ctes.map((cte, index) => [cte.name, index]));
+    const visited = new Set();
+    const visiting = new Set();
+    const ordered = [];
+    const visit = (name) => {
+        var _a, _b;
+        if (visited.has(name)) {
+            return;
+        }
+        if (visiting.has(name)) {
+            throw new Error(`Circular CTE dependency detected while planning: ${name}`);
+        }
+        visiting.add(name);
+        const dependencies = [...((_b = (_a = cteMap.get(name)) === null || _a === void 0 ? void 0 : _a.depends_on) !== null && _b !== void 0 ? _b : [])].sort((left, right) => { var _a, _b; return ((_a = cteOrder.get(left)) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER) - ((_b = cteOrder.get(right)) !== null && _b !== void 0 ? _b : Number.MAX_SAFE_INTEGER); });
+        // Visit dependencies first so every emitted step is ready to execute.
+        for (const dependency of dependencies) {
+            visit(dependency);
+        }
+        visiting.delete(name);
+        visited.add(name);
+        ordered.push(name);
+    };
+    for (const cte of report.ctes) {
+        visit(cte.name);
+    }
+    return ordered;
+}
+function uniquePreservingOrder(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}
+//# sourceMappingURL=planner.js.map

package/dist/query/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","sourceRoot":"","sources":["../../src/query/planner.ts"],"names":[],"mappings":"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"}

package/dist/query/report.d.ts

@@ -0,0 +1,7 @@
+import { QUERY_USES_REPORT_SPANS, writeQueryUsageOutput } from '@rawsql-ts/sql-grep-core';
+import type { BuildQueryUsageReportParams } from '@rawsql-ts/sql-grep-core';
+export { QUERY_USES_REPORT_SPANS, writeQueryUsageOutput };
+/**
+ * Build a deterministic impact or detail investigation report from catalog specs.
+ */
+export declare function buildQueryUsageReport(params: Omit<BuildQueryUsageReportParams, 'withSpanSync'>): import("@rawsql-ts/sql-grep-core").QueryUsageReport;

package/dist/query/report.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeQueryUsageOutput = exports.QUERY_USES_REPORT_SPANS = void 0;
+exports.buildQueryUsageReport = buildQueryUsageReport;
+const sql_grep_core_1 = require("@rawsql-ts/sql-grep-core");
+Object.defineProperty(exports, "QUERY_USES_REPORT_SPANS", { enumerable: true, get: function () { return sql_grep_core_1.QUERY_USES_REPORT_SPANS; } });
+Object.defineProperty(exports, "writeQueryUsageOutput", { enumerable: true, get: function () { return sql_grep_core_1.writeQueryUsageOutput; } });
+const telemetry_1 = require("../utils/telemetry");
+const runQueryUsageSpan = (name, fn, attrs) => (0, telemetry_1.withSpanSync)(name, fn, attrs);
+/**
+ * Build a deterministic impact or detail investigation report from catalog specs.
+ */
+function buildQueryUsageReport(params) {
+    return (0, sql_grep_core_1.buildQueryUsageReport)({
+        ...params,
+        withSpanSync: runQueryUsageSpan,
+    });
+}
+//# sourceMappingURL=report.js.map

package/dist/query/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/query/report.ts"],"names":[],"mappings":";;;AAiBA,sDAKC;AAtBD,4DAIkC;AAKzB,wGAPP,uCAAuB,OAOO;AAAE,sGANhC,qCAAqB,OAMgC;AAHvD,kDAAkD;AAKlD,MAAM,iBAAiB,GAA6D,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,CACtG,IAAA,wBAAY,EAAC,IAAI,EAAE,EAAE,EAAE,KAA4B,CAAC,CAAC;AAEvD;;GAEG;AACH,SAAgB,qBAAqB,CAAC,MAAyD;IAC7F,OAAO,IAAA,qCAAyB,EAAC;QAC/B,GAAG,MAAM;QACT,YAAY,EAAE,iBAAiB;KAChC,CAAC,CAAC;AACL,CAAC"}

package/dist/query/scalarFilterAnalysis.d.ts

@@ -0,0 +1,6 @@
+import { type SupportedStatement } from './analysis';
+/**
+ * Detect non-correlated WHERE scalar subqueries that are good scalar-filter binding candidates.
+ */
+export declare function findScalarFilterCandidates(sqlFile: string): string[];
+export declare function findScalarFilterCandidatesInStatement(statement: SupportedStatement): string[];