feat: add SelectQueryParser.analyze method with character-level error positioning

root · claude · root · commit 7802625e94db · 2025-07-25T22:46:03.000+09:00
Added analyze() method to SelectQueryParser that provides non-throwing parsing with detailed error information including precise character positions instead of token indices. Features: - ParseAnalysisResult interface with success status, query, and error details - Character-level error positioning for better IDE integration - Support for remaining tokens detection after complete queries - Comprehensive error handling with fallback position calculation - Maintains backward compatibility with existing parse() method The analyze method enables better error reporting and debugging capabilities for SQL parsing, making it easier to integrate with editors and IDEs. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -1,5 +1,6 @@
 // Entry point for rawsql-ts package
 export * from './parsers/SelectQueryParser';
+export { ParseAnalysisResult } from './parsers/SelectQueryParser';
 export * from './parsers/InsertQueryParser';
 export * from './parsers/WithClauseParser';
 
diff --git a/packages/core/src/parsers/SelectQueryParser.ts b/packages/core/src/parsers/SelectQueryParser.ts
@@ -15,6 +15,14 @@ import { ValuesQueryParser } from "./ValuesQueryParser";
 import { FetchClauseParser } from "./FetchClauseParser";
 import { OffsetClauseParser } from "./OffsetClauseParser";
 
+export interface ParseAnalysisResult {
+    success: boolean;
+    query?: SelectQuery;
+    error?: string;
+    errorPosition?: number; // Character position in source text
+    remainingTokens?: string[];
+}
+
 export class SelectQueryParser {
     // Parse SQL string to AST (was: parse)
     public static parse(query: string): SelectQuery {
@@ -32,6 +40,94 @@ export class SelectQueryParser {
         return result.value;
     }
 
+    /**
+     * Analyzes SQL string for parsing without throwing errors.
+     * Returns a result object containing the parsed query on success,
+     * or error information if parsing fails.
+     *
+     * @param query SQL string to analyze
+     * @returns Analysis result containing query, error information, and success status
+     */
+    /**
+     * Calculate character position from token index by finding token in original query
+     */
+    private static calculateCharacterPosition(query: string, lexemes: Lexeme[], tokenIndex: number): number {
+        if (tokenIndex >= lexemes.length) {
+            return query.length;
+        }
+        
+        // If lexeme has position information, use it
+        const lexeme = lexemes[tokenIndex];
+        if (lexeme.position?.startPosition !== undefined) {
+            return lexeme.position.startPosition;
+        }
+        
+        // Fallback: search for token in original query
+        // Build search pattern from tokens up to the target
+        let searchStart = 0;
+        for (let i = 0; i < tokenIndex; i++) {
+            const tokenValue = lexemes[i].value;
+            const tokenPos = query.indexOf(tokenValue, searchStart);
+            if (tokenPos !== -1) {
+                searchStart = tokenPos + tokenValue.length;
+            }
+        }
+        
+        const targetToken = lexemes[tokenIndex].value;
+        const tokenPos = query.indexOf(targetToken, searchStart);
+        return tokenPos !== -1 ? tokenPos : searchStart;
+    }
+
+    public static analyze(query: string): ParseAnalysisResult {
+        let lexemes: Lexeme[] = [];
+        
+        try {
+            const tokenizer = new SqlTokenizer(query);
+            lexemes = tokenizer.readLexmes();
+
+            // Parse
+            const result = this.parseFromLexeme(lexemes, 0);
+
+            // Check for remaining tokens
+            if (result.newIndex < lexemes.length) {
+                const remainingTokens = lexemes.slice(result.newIndex).map(lex => lex.value);
+                const errorLexeme = lexemes[result.newIndex];
+                const errorPosition = this.calculateCharacterPosition(query, lexemes, result.newIndex);
+                
+                return {
+                    success: false,
+                    query: result.value,
+                    error: `Syntax error: Unexpected token "${errorLexeme.value}" at character position ${errorPosition}. The SELECT query is complete but there are additional tokens.`,
+                    errorPosition: errorPosition,
+                    remainingTokens: remainingTokens
+                };
+            }
+
+            return {
+                success: true,
+                query: result.value
+            };
+        } catch (error) {
+            // Extract position information from error message if available
+            let errorPosition: number | undefined;
+            
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            
+            // Try to extract token index from error message and convert to character position
+            const positionMatch = errorMessage.match(/position (\d+)/);
+            if (positionMatch) {
+                const tokenIndex = parseInt(positionMatch[1], 10);
+                errorPosition = this.calculateCharacterPosition(query, lexemes, tokenIndex);
+            }
+
+            return {
+                success: false,
+                error: errorMessage,
+                errorPosition: errorPosition
+            };
+        }
+    }
+
     /**
      * Asynchronously parse SQL string to AST.
      * This method wraps the synchronous parse logic in a Promise for future extensibility.
diff --git a/packages/core/tests/parsers/SelectQueryParser.analyze.test.ts b/packages/core/tests/parsers/SelectQueryParser.analyze.test.ts
@@ -0,0 +1,190 @@
+import { describe, expect, test } from 'vitest';
+import { SelectQueryParser } from '../../src/parsers/SelectQueryParser';
+
+describe('SelectQueryParser.analyze', () => {
+    test('should successfully analyze valid SELECT query', () => {
+        // Arrange
+        const sql = `SELECT id, name FROM users WHERE active = true`;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+        expect(result.errorPosition).toBeUndefined();
+        expect(result.remainingTokens).toBeUndefined();
+    });
+
+    test('should successfully analyze complex query with JOIN', () => {
+        // Arrange
+        const sql = `
+            SELECT u.id, u.name, o.order_id 
+            FROM users u 
+            JOIN orders o ON u.id = o.user_id 
+            WHERE u.active = true
+        `;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should successfully parse query with alias (not missing FROM)', () => {
+        // Arrange
+        const sql = `SELECT id, name users`; // This is valid SQL: SELECT id, name AS users
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should successfully parse query with table alias', () => {
+        // Arrange
+        const sql = `SELECT id FROM users EXTRA_TOKEN`; // EXTRA_TOKEN is parsed as table alias
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should detect error when missing SELECT keyword', () => {
+        // Arrange
+        const sql = `UPDATE users SET name = 'test'`; // Wrong query type
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Expected 'SELECT' or 'VALUES'");
+        expect(result.errorPosition).toBe(0); // Character position of 'update'
+    });
+
+    test('should handle empty query', () => {
+        // Arrange
+        const sql = ``;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain('Unexpected end of input');
+    });
+
+    test('should analyze VALUES query successfully', () => {
+        // Arrange
+        const sql = `VALUES (1, 'John'), (2, 'Jane')`;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should analyze UNION query successfully', () => {
+        // Arrange
+        const sql = `
+            SELECT id, name FROM users 
+            UNION 
+            SELECT id, title FROM posts
+        `;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should detect error in UNION query with incomplete second part', () => {
+        // Arrange
+        const sql = `SELECT id FROM users UNION`; // Incomplete UNION
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain("Expected a query after 'UNION'");
+    });
+
+    test('should analyze WITH clause query successfully', () => {
+        // Arrange
+        const sql = `
+            WITH user_data AS (SELECT * FROM users)
+            SELECT id, name FROM user_data
+        `;
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(true);
+        expect(result.query).toBeDefined();
+        expect(result.error).toBeUndefined();
+    });
+
+    test('should detect invalid FROM clause syntax', () => {
+        // Arrange
+        const sql = `SELECT id FROM FROM users`; // Invalid double FROM
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain('Identifier list is empty');
+    });
+
+    test('should detect incomplete FROM clause', () => {
+        // Arrange
+        const sql = `SELECT id FROM`; // Incomplete FROM clause
+
+        // Act
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.error).toBeDefined();
+        expect(result.error).toContain('Unexpected end of input after \'FROM\' keyword');
+    });
+
+    test('should detect remaining tokens after complete query', () => {
+        // Arrange
+        const sql = `SELECT * FROM users LIMIT 10 INVALID_KEYWORD`; 
+
+        // Act  
+        const result = SelectQueryParser.analyze(sql);
+
+        // Assert
+        expect(result.success).toBe(false);
+        expect(result.query).toBeDefined(); // Partial parsing successful
+        expect(result.error).toContain('Unexpected token "INVALID_KEYWORD"');
+        expect(result.errorPosition).toBe(29); // Character position of 'INVALID_KEYWORD'
+        expect(result.remainingTokens).toEqual(['INVALID_KEYWORD']);
+    });
+});
