Merge pull request #180 from mk3008/feat_schema_collector

feat: add SchemaCollector.analyze method for non-throwing schema analysis

Author: mk3008

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "rawsql-ts",
-    "version": "0.11.22-beta",
+    "version": "0.11.23-beta",
     "description": "[beta]High-performance SQL parser and AST analyzer written in TypeScript. Provides fast parsing and advanced transformation capabilities.",
     "main": "dist/src/index.js",
     "module": "dist/esm/index.js",

packages/core/package.json

@@ -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';
 
@@ -52,6 +53,7 @@ export * from './transformers/UpstreamSelectQueryFinder';
 export * from './transformers/TypeTransformationPostProcessor';
 
 export * from './transformers/SchemaCollector';
+export { TableSchema, SchemaAnalysisResult } from './transformers/SchemaCollector';
 export * from './transformers/QueryFlowDiagramGenerator';
 export * from './transformers/SqlParamInjector';
 export * from './transformers/SqlSortInjector';

packages/core/src/index.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.

packages/core/src/parsers/SelectQueryParser.ts

@@ -19,6 +19,13 @@ export class TableSchema {
     }
 }
 
+export interface SchemaAnalysisResult {
+    success: boolean;
+    schemas: TableSchema[];
+    unresolvedColumns: string[];
+    error?: string;
+}
+
 /**
  * A visitor that collects schema information (table names and column names) from a SQL query structure.
  */
@@ -29,6 +36,11 @@ export class SchemaCollector implements SqlComponentVisitor<void> {
     private visitedNodes: Set<SqlComponent> = new Set();
     private commonTables: CommonTable[] = [];
     private running = false;
+    
+    // For analyze method
+    private unresolvedColumns: string[] = [];
+    private analysisError: string | undefined = undefined;
+    private isAnalyzeMode = false;
 
     constructor(
         private tableColumnResolver: TableColumnResolver | null = null,
@@ -53,6 +65,34 @@ export class SchemaCollector implements SqlComponentVisitor<void> {
         return this.tableSchemas;
     }
 
+    /**
+     * Analyzes schema information from a SQL query structure without throwing errors.
+     * Returns a result object containing successfully resolved schemas, unresolved columns,
+     * and error information if any issues were encountered.
+     *
+     * @param arg The SQL query structure to analyze.
+     * @returns Analysis result containing schemas, unresolved columns, and success status.
+     */
+    public analyze(arg: SqlComponent): SchemaAnalysisResult {
+        // Set analyze mode flag
+        this.isAnalyzeMode = true;
+        
+        try {
+            this.visit(arg);
+            
+            // If we got here without errors, it's a success
+            return {
+                success: this.unresolvedColumns.length === 0 && !this.analysisError,
+                schemas: this.tableSchemas,
+                unresolvedColumns: this.unresolvedColumns,
+                error: this.analysisError
+            };
+        } finally {
+            // Reset analyze mode flag
+            this.isAnalyzeMode = false;
+        }
+    }
+
     /**
      * Main entry point for the visitor pattern.
      * Implements the shallow visit pattern to distinguish between root and recursive visits.
@@ -122,6 +162,8 @@ export class SchemaCollector implements SqlComponentVisitor<void> {
         this.tableSchemas = [];
         this.visitedNodes = new Set();
         this.commonTables = [];
+        this.unresolvedColumns = [];
+        this.analysisError = undefined;
     }
 
     /**
@@ -235,11 +277,18 @@ export class SchemaCollector implements SqlComponentVisitor<void> {
                 }));
         }
 
-        // Throw an error if there are columns without table names in queries with joins
+        // Handle columns without table names in queries with joins
         if (query.fromClause.joins !== null && query.fromClause.joins.length > 0) {
             const columnsWithoutTable = queryColumns.filter((columnRef) => columnRef.table === "").map((columnRef) => columnRef.column);
             if (columnsWithoutTable.length > 0) {
-                throw new Error(`Column reference(s) without table name found in query: ${columnsWithoutTable.join(', ')}`);
+                if (this.isAnalyzeMode) {
+                    // In analyze mode, collect unresolved columns
+                    this.unresolvedColumns.push(...columnsWithoutTable);
+                    this.analysisError = `Column reference(s) without table name found in query: ${columnsWithoutTable.join(', ')}`;
+                } else {
+                    // In collect mode, throw error as before
+                    throw new Error(`Column reference(s) without table name found in query: ${columnsWithoutTable.join(', ')}`);
+                }
             }
         }
 
@@ -296,12 +345,25 @@ export class SchemaCollector implements SqlComponentVisitor<void> {
                 .filter((columnRef) => columnRef.column === "*")
                 .length > 0;
 
-            // Throw error if wildcard is found and allowWildcardWithoutResolver is false (default behavior)
+            // Handle error if wildcard is found and allowWildcardWithoutResolver is false (default behavior)
             if (hasWildcard && !this.allowWildcardWithoutResolver) {
                 const errorMessage = tableName
                     ? `Wildcard (*) is used. A TableColumnResolver is required to resolve wildcards. Target table: ${tableName}`
                     : "Wildcard (*) is used. A TableColumnResolver is required to resolve wildcards.";
-                throw new Error(errorMessage);
+                
+                if (this.isAnalyzeMode) {
+                    // In analyze mode, record the error but continue processing
+                    this.analysisError = errorMessage;
+                    // Add wildcard columns to unresolved list
+                    const wildcardColumns = queryColumns
+                        .filter((columnRef) => columnRef.table === tableAlias || (includeUnnamed && columnRef.table === ""))
+                        .filter((columnRef) => columnRef.column === "*")
+                        .map((columnRef) => columnRef.table ? `${columnRef.table}.*` : "*");
+                    this.unresolvedColumns.push(...wildcardColumns);
+                } else {
+                    // In collect mode, throw error as before
+                    throw new Error(errorMessage);
+                }
             }
         }