rawsql-ts 0.11.29-beta → 0.11.31-beta

package/dist/src/utils/CTERegionDetector.js

@@ -0,0 +1,464 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CTERegionDetector = void 0;
+const Lexeme_1 = require("../models/Lexeme");
+const LexemeCursor_1 = require("./LexemeCursor");
+/**
+ * Utility class for detecting CTE (Common Table Expression) regions and extracting executable SQL.
+ *
+ * Designed for SQL editor features where users want to execute specific CTE parts based on cursor position.
+ * This enables editors to provide "run current section" functionality that intelligently executes
+ * either the CTE the cursor is in, or the main query.
+ *
+ * @example Basic usage - Analyze cursor position
+ * ```typescript
+ * const sql = `
+ *   WITH users_cte AS (
+ *     SELECT id, name FROM users WHERE active = true
+ *   )
+ *   SELECT * FROM users_cte ORDER BY name
+ * `;
+ *
+ * const cursorPosition = 50; // Inside the CTE
+ * const analysis = CTERegionDetector.analyzeCursorPosition(sql, cursorPosition);
+ *
+ * if (analysis.isInCTE) {
+ *   console.log(`Execute CTE: ${analysis.cteRegion.name}`);
+ *   executeSQL(analysis.executableSQL); // Runs just the CTE SELECT
+ * }
+ * ```
+ *
+ * @example Get all executable sections
+ * ```typescript
+ * const positions = CTERegionDetector.getCTEPositions(sql);
+ * // Returns: [
+ * //   { name: 'users_cte', startPosition: 17, type: 'CTE' },
+ * //   { name: 'MAIN_QUERY', startPosition: 120, type: 'MAIN_QUERY' }
+ * // ]
+ * ```
+ */
+class CTERegionDetector {
+    /**
+     * Analyze cursor position and return information about the current context.
+     *
+     * This is the main method for SQL editor integration. It determines whether the cursor
+     * is inside a CTE or the main query, and provides the appropriate executable SQL.
+     *
+     * @param sql - The complete SQL string to analyze
+     * @param cursorPosition - The cursor position (0-based character offset)
+     * @returns Analysis result containing context information and executable SQL
+     *
+     * @example
+     * ```typescript
+     * const sql = `WITH users AS (SELECT * FROM table) SELECT * FROM users`;
+     * const analysis = CTERegionDetector.analyzeCursorPosition(sql, 25);
+     *
+     * if (analysis.isInCTE) {
+     *   console.log(`Cursor is in CTE: ${analysis.cteRegion.name}`);
+     *   executeSQL(analysis.executableSQL); // Execute just the CTE
+     * } else {
+     *   console.log('Cursor is in main query');
+     *   executeSQL(analysis.executableSQL); // Execute the full query
+     * }
+     * ```
+     */
+    static analyzeCursorPosition(sql, cursorPosition) {
+        const cteRegions = this.extractCTERegions(sql);
+        const extendedRegions = this.calculateExtendedCTEBoundaries(sql, cteRegions);
+        // Find which CTE region contains the cursor using extended boundaries
+        const currentCTE = extendedRegions.find(region => cursorPosition >= region.startPosition && cursorPosition < region.extendedEndPosition);
+        if (currentCTE) {
+            return {
+                isInCTE: true,
+                cteRegion: {
+                    name: currentCTE.name,
+                    startPosition: currentCTE.startPosition,
+                    endPosition: currentCTE.endPosition,
+                    sqlContent: currentCTE.sqlContent
+                },
+                executableSQL: currentCTE.sqlContent
+            };
+        }
+        else {
+            // Cursor is in main query - return full SQL or main SELECT part
+            const mainSQL = this.extractMainQuery(sql, cteRegions);
+            return {
+                isInCTE: false,
+                cteRegion: null,
+                executableSQL: mainSQL
+            };
+        }
+    }
+    /**
+     * Get the CTE name at the specified cursor position (simplified interface).
+     *
+     * This method provides a simple interface for retrieving just the CTE name
+     * without additional context information.
+     *
+     * @param sql - The SQL string to analyze
+     * @param cursorPosition - The cursor position (0-based character offset)
+     * @returns The CTE name if cursor is in a CTE, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const sql = `WITH users AS (SELECT * FROM table) SELECT * FROM users`;
+     * const cteName = CTERegionDetector.getCursorCte(sql, 25);
+     * console.log(cteName); // "users"
+     * ```
+     */
+    static getCursorCte(sql, cursorPosition) {
+        var _a;
+        try {
+            const analysis = this.analyzeCursorPosition(sql, cursorPosition);
+            return analysis.isInCTE ? ((_a = analysis.cteRegion) === null || _a === void 0 ? void 0 : _a.name) || null : null;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Get the CTE name at the specified 2D coordinates (line, column).
+     *
+     * This method provides a convenient interface for editor integrations
+     * that work with line/column coordinates instead of character positions.
+     *
+     * @param sql - The SQL string to analyze
+     * @param line - The line number (1-based)
+     * @param column - The column number (1-based)
+     * @returns The CTE name if cursor is in a CTE, null otherwise
+     *
+     * @example
+     * ```typescript
+     * const sql = `WITH users AS (\n  SELECT * FROM table\n) SELECT * FROM users`;
+     * const cteName = CTERegionDetector.getCursorCteAt(sql, 2, 5);
+     * console.log(cteName); // "users"
+     * ```
+     */
+    static getCursorCteAt(sql, line, column) {
+        try {
+            const position = this.lineColumnToPosition(sql, line, column);
+            if (position === -1) {
+                return null;
+            }
+            return this.getCursorCte(sql, position);
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Convert line/column coordinates to character position.
+     *
+     * @param text - The text to analyze
+     * @param line - The line number (1-based)
+     * @param column - The column number (1-based)
+     * @returns The character position (0-based), or -1 if invalid coordinates
+     */
+    static lineColumnToPosition(text, line, column) {
+        if (line < 1 || column < 1) {
+            return -1;
+        }
+        const lines = text.split('\n');
+        if (line > lines.length) {
+            return -1;
+        }
+        const targetLine = lines[line - 1];
+        if (column > targetLine.length + 1) { // +1 to allow position at end of line
+            return -1;
+        }
+        // Calculate position by summing lengths of previous lines plus newlines
+        let position = 0;
+        for (let i = 0; i < line - 1; i++) {
+            position += lines[i].length + 1; // +1 for the newline character
+        }
+        position += column - 1; // column is 1-based, position is 0-based
+        return position;
+    }
+    /**
+     * Convert character position to line/column coordinates.
+     *
+     * @param text - The text to analyze
+     * @param position - The character position (0-based)
+     * @returns Object with line and column (1-based), or null if invalid position
+     */
+    static positionToLineColumn(text, position) {
+        if (position < 0 || position > text.length) {
+            return null;
+        }
+        const beforePosition = text.substring(0, position);
+        const lines = beforePosition.split('\n');
+        return {
+            line: lines.length,
+            column: lines[lines.length - 1].length + 1
+        };
+    }
+    /**
+     * Extract all CTE regions from SQL text with their boundaries and executable content.
+     *
+     * Parses the SQL to identify all Common Table Expressions and their locations,
+     * providing the information needed for syntax highlighting, code folding, and selective execution.
+     *
+     * @param sql - The SQL string to analyze
+     * @returns Array of CTE regions with their boundaries and content
+     *
+     * @example
+     * ```typescript
+     * const sql = `
+     *   WITH
+     *     users AS (SELECT * FROM people),
+     *     orders AS (SELECT * FROM purchases)
+     *   SELECT * FROM users JOIN orders
+     * `;
+     *
+     * const regions = CTERegionDetector.extractCTERegions(sql);
+     * // Returns: [
+     * //   { name: 'users', startPosition: 23, endPosition: 45, sqlContent: 'SELECT * FROM people' },
+     * //   { name: 'orders', startPosition: 55, endPosition: 80, sqlContent: 'SELECT * FROM purchases' }
+     * // ]
+     * ```
+     */
+    static extractCTERegions(sql) {
+        const lexemes = LexemeCursor_1.LexemeCursor.getAllLexemesWithPosition(sql);
+        const cteRegions = [];
+        let i = 0;
+        let inWithClause = false;
+        while (i < lexemes.length) {
+            const lexeme = lexemes[i];
+            // Detect WITH clause start
+            if (lexeme.value.toLowerCase() === 'with' && !inWithClause) {
+                inWithClause = true;
+                i++;
+                continue;
+            }
+            // Skip RECURSIVE keyword if present
+            if (inWithClause && lexeme.value.toLowerCase() === 'recursive') {
+                i++;
+                continue;
+            }
+            // Detect CTE definition (identifier followed by AS)
+            if (inWithClause &&
+                lexeme.type === Lexeme_1.TokenType.Identifier &&
+                i + 1 < lexemes.length &&
+                lexemes[i + 1].value.toLowerCase() === 'as') {
+                const cteName = lexeme.value;
+                const cteStartPos = lexeme.position.startPosition;
+                // Find the opening parenthesis after AS
+                let parenIndex = i + 2;
+                while (parenIndex < lexemes.length && lexemes[parenIndex].value !== '(') {
+                    parenIndex++;
+                }
+                if (parenIndex < lexemes.length) {
+                    // Find matching closing parenthesis
+                    const cteEndInfo = this.findMatchingParen(lexemes, parenIndex);
+                    if (cteEndInfo) {
+                        const cteEndPos = cteEndInfo.endPosition;
+                        const sqlContent = this.extractCTESQL(sql, lexemes, parenIndex, cteEndInfo.index);
+                        cteRegions.push({
+                            name: cteName,
+                            startPosition: cteStartPos,
+                            endPosition: cteEndPos,
+                            sqlContent: sqlContent
+                        });
+                        i = cteEndInfo.index + 1;
+                        continue;
+                    }
+                }
+            }
+            // Check if we've reached the main SELECT (end of WITH clause)
+            if (inWithClause && lexeme.value.toLowerCase() === 'select') {
+                // Verify this is not a SELECT inside a CTE by checking context
+                if (this.isMainQuerySelect(lexemes, i)) {
+                    break;
+                }
+            }
+            i++;
+        }
+        return cteRegions;
+    }
+    /**
+     * Find matching closing parenthesis for CTE definition
+     */
+    static findMatchingParen(lexemes, openParenIndex) {
+        let depth = 1;
+        let i = openParenIndex + 1;
+        while (i < lexemes.length && depth > 0) {
+            if (lexemes[i].value === '(') {
+                depth++;
+            }
+            else if (lexemes[i].value === ')') {
+                depth--;
+            }
+            if (depth === 0) {
+                return {
+                    index: i,
+                    endPosition: lexemes[i].position.endPosition
+                };
+            }
+            i++;
+        }
+        return null;
+    }
+    /**
+     * Extract the SQL content of a CTE (the SELECT statement inside parentheses)
+     */
+    static extractCTESQL(sql, lexemes, openParenIndex, closeParenIndex) {
+        const startPos = lexemes[openParenIndex + 1].position.startPosition;
+        const endPos = lexemes[closeParenIndex - 1].position.endPosition;
+        return sql.substring(startPos, endPos).trim();
+    }
+    /**
+     * Check if a SELECT lexeme is the main query SELECT (not inside a CTE)
+     */
+    static isMainQuerySelect(lexemes, selectIndex) {
+        // Look backwards to see if we're still in a parenthesized context
+        let depth = 0;
+        for (let i = selectIndex - 1; i >= 0; i--) {
+            if (lexemes[i].value === ')') {
+                depth++;
+            }
+            else if (lexemes[i].value === '(') {
+                depth--;
+            }
+        }
+        return depth === 0; // We're at top level if depth is 0
+    }
+    /**
+     * Calculate extended CTE boundaries for better cursor position detection.
+     * Extended boundaries include the space between CTEs and before the main query.
+     */
+    static calculateExtendedCTEBoundaries(sql, cteRegions) {
+        if (cteRegions.length === 0) {
+            return [];
+        }
+        return cteRegions.map((region, index) => {
+            let extendedEndPosition;
+            if (index < cteRegions.length - 1) {
+                // Not the last CTE - extend to the start of the next CTE
+                extendedEndPosition = cteRegions[index + 1].startPosition;
+            }
+            else {
+                // Last CTE - extend to the start of the main query
+                const mainQueryStart = this.findMainQueryStart(sql, region.endPosition);
+                extendedEndPosition = mainQueryStart;
+            }
+            return {
+                ...region,
+                extendedEndPosition
+            };
+        });
+    }
+    /**
+     * Find the start position of the main query after the last CTE
+     */
+    static findMainQueryStart(sql, afterPosition) {
+        // Look for the main SELECT keyword after the CTE definitions
+        let pos = afterPosition;
+        while (pos < sql.length) {
+            const remaining = sql.substring(pos).toLowerCase().trim();
+            if (remaining.startsWith('select')) {
+                // Find the actual position of SELECT in the original text
+                const selectIndex = sql.toLowerCase().indexOf('select', pos);
+                return selectIndex !== -1 ? selectIndex : pos;
+            }
+            pos++;
+        }
+        return sql.length; // If no main query found, extend to end of string
+    }
+    /**
+     * Extract the main query part (non-CTE SQL)
+     */
+    static extractMainQuery(sql, cteRegions) {
+        if (cteRegions.length === 0) {
+            return sql.trim();
+        }
+        // Find the end of the last CTE
+        const lastCTE = cteRegions[cteRegions.length - 1];
+        const mainQueryStart = lastCTE.endPosition;
+        // Find the main SELECT
+        let selectPos = mainQueryStart;
+        while (selectPos < sql.length) {
+            const remaining = sql.substring(selectPos).toLowerCase().trim();
+            if (remaining.startsWith('select')) {
+                break;
+            }
+            selectPos++;
+        }
+        return sql.substring(selectPos).trim();
+    }
+    /**
+     * Get a list of all executable sections (CTEs and main query) with their start positions.
+     *
+     * This method is particularly useful for building editor UI features such as:
+     * - Dropdown menus for section selection
+     * - Sidebar navigation for large queries
+     * - Quick jump functionality
+     * - "Run section" buttons
+     *
+     * @param sql - The SQL string to analyze
+     * @returns Array of executable sections with their names, positions, and types
+     *
+     * @example
+     * ```typescript
+     * const sql = `
+     *   WITH monthly_sales AS (SELECT ...),
+     *        yearly_summary AS (SELECT ...)
+     *   SELECT * FROM yearly_summary
+     * `;
+     *
+     * const positions = CTERegionDetector.getCTEPositions(sql);
+     * // Returns: [
+     * //   { name: 'monthly_sales', startPosition: 17, type: 'CTE' },
+     * //   { name: 'yearly_summary', startPosition: 55, type: 'CTE' },
+     * //   { name: 'MAIN_QUERY', startPosition: 120, type: 'MAIN_QUERY' }
+     * // ]
+     *
+     * // Use for editor UI
+     * positions.forEach(section => {
+     *   addMenuItem(`${section.type}: ${section.name}`, () => {
+     *     jumpToPosition(section.startPosition);
+     *   });
+     * });
+     * ```
+     */
+    static getCTEPositions(sql) {
+        const cteRegions = this.extractCTERegions(sql);
+        const results = [];
+        // Add CTE regions
+        cteRegions.forEach(region => {
+            results.push({
+                name: region.name,
+                startPosition: region.startPosition,
+                type: 'CTE'
+            });
+        });
+        // Add main query position
+        if (cteRegions.length > 0) {
+            const lastCTE = cteRegions[cteRegions.length - 1];
+            let mainQueryPos = lastCTE.endPosition;
+            // Find the SELECT keyword
+            while (mainQueryPos < sql.length) {
+                const remaining = sql.substring(mainQueryPos).toLowerCase().trim();
+                if (remaining.startsWith('select')) {
+                    results.push({
+                        name: 'MAIN_QUERY',
+                        startPosition: mainQueryPos,
+                        type: 'MAIN_QUERY'
+                    });
+                    break;
+                }
+                mainQueryPos++;
+            }
+        }
+        else {
+            // No CTEs, entire SQL is main query
+            results.push({
+                name: 'MAIN_QUERY',
+                startPosition: 0,
+                type: 'MAIN_QUERY'
+            });
+        }
+        return results;
+    }
+}
+exports.CTERegionDetector = CTERegionDetector;
+//# sourceMappingURL=CTERegionDetector.js.map

package/dist/src/utils/CTERegionDetector.js.map

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

package/dist/src/utils/LexemeCursor.d.ts

@@ -1,27 +1,58 @@
 import { Lexeme } from '../models/Lexeme';
 /**
- * Utility class for cursor-to-lexeme mapping in SQL text
- * Provides functionality to find lexemes at specific cursor positions for IDE integration
+ * Utility class for cursor-to-lexeme mapping in SQL text.
+ *
+ * Provides functionality to find lexemes at specific cursor positions for IDE integration.
+ * Handles SQL parsing with proper comment and whitespace handling for editor features.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const sql = "SELECT id FROM users WHERE active = true";
+ * const lexeme = LexemeCursor.findLexemeAtPosition(sql, 7); // position at 'id'
+ * console.log(lexeme?.value); // 'id'
+ * ```
  */
 export declare class LexemeCursor {
     private static readonly SQL_COMMANDS;
     /**
-     * Find the lexeme at the specified cursor position
-     * @param sql The SQL string
-     * @param cursorPosition The cursor position (0-based)
+     * Find the lexeme at the specified cursor position.
+     *
+     * Performs intelligent SQL parsing with proper comment and whitespace handling.
+     * Returns null if cursor is in whitespace or comments.
+     *
+     * @param sql - The SQL string to analyze
+     * @param cursorPosition - The cursor position (0-based character offset)
      * @returns The lexeme at the position, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const sql = "SELECT user_id FROM orders";
+     * const lexeme = LexemeCursor.findLexemeAtPosition(sql, 7);
+     * console.log(lexeme?.value); // 'user_id'
+     * ```
      */
     static findLexemeAtPosition(sql: string, cursorPosition: number): Lexeme | null;
     /**
-     * Get all lexemes with position information
-     * @param sql The SQL string
-     * @returns Array of lexemes with position information
+     * Get all lexemes with position information from SQL text.
+     *
+     * Tokenizes the entire SQL string with precise position information.
+     * Useful for syntax highlighting, code analysis, and editor features.
+     *
+     * @param sql - The SQL string to tokenize
+     * @returns Array of lexemes with position information (excludes comments/whitespace)
+     *
+     * @example
+     * ```typescript
+     * const sql = "SELECT id FROM users";
+     * const lexemes = LexemeCursor.getAllLexemesWithPosition(sql);
+     * lexemes.forEach(l => console.log(`${l.value} at ${l.position.startPosition}`));
+     * ```
      */
     static getAllLexemesWithPosition(sql: string): Lexeme[];
     /**
-     * Skip whitespace characters
+     * Skip whitespace and comments, returning new position
      */
-    private static skipWhitespace;
+    private static skipWhitespaceAndComments;
     /**
      * Parse the next token starting at the given position
      */

package/dist/src/utils/LexemeCursor.js

@@ -2,16 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LexemeCursor = void 0;
 const Lexeme_1 = require("../models/Lexeme");
+const stringUtils_1 = require("./stringUtils");
 /**
- * Utility class for cursor-to-lexeme mapping in SQL text
- * Provides functionality to find lexemes at specific cursor positions for IDE integration
+ * Utility class for cursor-to-lexeme mapping in SQL text.
+ *
+ * Provides functionality to find lexemes at specific cursor positions for IDE integration.
+ * Handles SQL parsing with proper comment and whitespace handling for editor features.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const sql = "SELECT id FROM users WHERE active = true";
+ * const lexeme = LexemeCursor.findLexemeAtPosition(sql, 7); // position at 'id'
+ * console.log(lexeme?.value); // 'id'
+ * ```
  */
 class LexemeCursor {
     /**
-     * Find the lexeme at the specified cursor position
-     * @param sql The SQL string
-     * @param cursorPosition The cursor position (0-based)
+     * Find the lexeme at the specified cursor position.
+     *
+     * Performs intelligent SQL parsing with proper comment and whitespace handling.
+     * Returns null if cursor is in whitespace or comments.
+     *
+     * @param sql - The SQL string to analyze
+     * @param cursorPosition - The cursor position (0-based character offset)
      * @returns The lexeme at the position, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const sql = "SELECT user_id FROM orders";
+     * const lexeme = LexemeCursor.findLexemeAtPosition(sql, 7);
+     * console.log(lexeme?.value); // 'user_id'
+     * ```
      */
     static findLexemeAtPosition(sql, cursorPosition) {
         if (cursorPosition < 0 || cursorPosition >= sql.length) {
@@ -28,9 +49,20 @@ class LexemeCursor {
         return null;
     }
     /**
-     * Get all lexemes with position information
-     * @param sql The SQL string
-     * @returns Array of lexemes with position information
+     * Get all lexemes with position information from SQL text.
+     *
+     * Tokenizes the entire SQL string with precise position information.
+     * Useful for syntax highlighting, code analysis, and editor features.
+     *
+     * @param sql - The SQL string to tokenize
+     * @returns Array of lexemes with position information (excludes comments/whitespace)
+     *
+     * @example
+     * ```typescript
+     * const sql = "SELECT id FROM users";
+     * const lexemes = LexemeCursor.getAllLexemesWithPosition(sql);
+     * lexemes.forEach(l => console.log(`${l.value} at ${l.position.startPosition}`));
+     * ```
      */
     static getAllLexemesWithPosition(sql) {
         if (!(sql === null || sql === void 0 ? void 0 : sql.trim())) {
@@ -40,7 +72,7 @@ class LexemeCursor {
             const lexemes = [];
             let position = 0;
             while (position < sql.length) {
-                position = this.skipWhitespace(sql, position);
+                position = this.skipWhitespaceAndComments(sql, position);
                 if (position >= sql.length) {
                     break;
                 }
@@ -60,13 +92,11 @@ class LexemeCursor {
         }
     }
     /**
-     * Skip whitespace characters
+     * Skip whitespace and comments, returning new position
      */
-    static skipWhitespace(sql, position) {
-        while (position < sql.length && /\s/.test(sql[position])) {
-            position++;
-        }
-        return position;
+    static skipWhitespaceAndComments(sql, position) {
+        const result = stringUtils_1.StringUtils.readWhiteSpaceAndComment(sql, position);
+        return result.position;
     }
     /**
      * Parse the next token starting at the given position
@@ -153,7 +183,7 @@ class LexemeCursor {
             return Lexeme_1.TokenType.Command;
         }
         // Check if it's followed by parentheses (function)
-        const nextNonWhitespacePos = this.skipWhitespace(sql, position);
+        const nextNonWhitespacePos = this.skipWhitespaceAndComments(sql, position);
         if (nextNonWhitespacePos < sql.length && sql[nextNonWhitespacePos] === '(') {
             return Lexeme_1.TokenType.Function;
         }