@gblikas/querykit 0.2.0 → 0.4.0

package/dist/parser/parser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryParser = exports.QueryParseError = void 0;
 const liqe_1 = require("liqe");
+const input_parser_1 = require("./input-parser");
 /**
  * Error thrown when query parsing fails
  */
@@ -355,5 +356,720 @@ class QueryParser {
             : field;
         return this.options.fieldMappings[normalizedField] ?? normalizedField;
     }
+    /**
+     * Parse a query string with full context information.
+     *
+     * Unlike `parse()`, this method never throws. Instead, it returns a result object
+     * that indicates success or failure along with rich contextual information useful
+     * for building search UIs.
+     *
+     * @param query The query string to parse
+     * @param options Optional configuration (cursor position, etc.)
+     * @returns Rich parse result with tokens, AST/error, and structural analysis
+     *
+     * @example
+     * ```typescript
+     * const result = parser.parseWithContext('status:done AND priority:high');
+     *
+     * if (result.success) {
+     *   // Use result.ast for query execution
+     *   console.log('Valid query:', result.ast);
+     * } else {
+     *   // Show error to user
+     *   console.log('Error:', result.error?.message);
+     * }
+     *
+     * // Always available for UI rendering
+     * console.log('Tokens:', result.tokens);
+     * console.log('Structure:', result.structure);
+     * ```
+     */
+    parseWithContext(query, options = {}) {
+        // Get tokens from input parser (always works, even for invalid input)
+        const tokenResult = (0, input_parser_1.parseQueryTokens)(query, options.cursorPosition);
+        const tokens = this.convertTokens(tokenResult.tokens);
+        // Analyze structure
+        const structure = this.analyzeStructure(query, tokens);
+        // Attempt full parse
+        let ast;
+        let error;
+        let success = false;
+        try {
+            ast = this.parse(query);
+            success = true;
+        }
+        catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            error = {
+                message: errorMessage,
+                // Try to extract position from error message if available
+                position: this.extractErrorPosition(errorMessage),
+                problematicText: this.extractProblematicText(query, errorMessage)
+            };
+        }
+        // Determine active token
+        const activeToken = tokenResult.activeToken
+            ? this.convertSingleToken(tokenResult.activeToken)
+            : undefined;
+        // Build base result
+        const result = {
+            success,
+            input: query,
+            ast,
+            error,
+            tokens,
+            activeToken,
+            activeTokenIndex: tokenResult.activeTokenIndex,
+            structure
+        };
+        // Perform field validation if schema provided
+        if (options.schema) {
+            result.fieldValidation = this.validateFields(structure.referencedFields, options.schema);
+        }
+        // Perform security pre-check if security options provided
+        if (options.securityOptions) {
+            result.security = this.performSecurityCheck(structure, options.securityOptions);
+        }
+        // Generate autocomplete suggestions if cursor position provided
+        if (options.cursorPosition !== undefined) {
+            result.suggestions = this.generateAutocompleteSuggestions(query, options.cursorPosition, activeToken, options.schema);
+        }
+        // Generate error recovery suggestions if parsing failed
+        if (!success) {
+            result.recovery = this.generateErrorRecovery(query, structure);
+        }
+        return result;
+    }
+    /**
+     * Convert tokens from input parser format to IQueryToken format
+     */
+    convertTokens(tokens) {
+        return tokens.map(token => this.convertSingleToken(token));
+    }
+    /**
+     * Convert a single token from input parser format
+     */
+    convertSingleToken(token) {
+        if (token.type === 'term') {
+            return {
+                type: 'term',
+                key: token.key,
+                operator: token.operator,
+                value: token.value,
+                startPosition: token.startPosition,
+                endPosition: token.endPosition,
+                raw: token.raw
+            };
+        }
+        else {
+            return {
+                type: 'operator',
+                operator: token.operator,
+                startPosition: token.startPosition,
+                endPosition: token.endPosition,
+                raw: token.raw
+            };
+        }
+    }
+    /**
+     * Analyze the structure of a query
+     */
+    analyzeStructure(query, tokens) {
+        // Count parentheses
+        const openParens = (query.match(/\(/g) || []).length;
+        const closeParens = (query.match(/\)/g) || []).length;
+        const hasBalancedParentheses = openParens === closeParens;
+        // Count quotes
+        const singleQuotes = (query.match(/'/g) || []).length;
+        const doubleQuotes = (query.match(/"/g) || []).length;
+        const hasBalancedQuotes = singleQuotes % 2 === 0 && doubleQuotes % 2 === 0;
+        // Count terms and operators
+        const termTokens = tokens.filter(t => t.type === 'term');
+        const operatorTokens = tokens.filter(t => t.type === 'operator');
+        const clauseCount = termTokens.length;
+        const operatorCount = operatorTokens.length;
+        // Extract referenced fields
+        const referencedFields = [];
+        for (const token of termTokens) {
+            if (token.type === 'term' && token.key !== null) {
+                if (!referencedFields.includes(token.key)) {
+                    referencedFields.push(token.key);
+                }
+            }
+        }
+        // Calculate depth (by counting max nesting in parentheses)
+        const depth = this.calculateDepth(query);
+        // Check if complete
+        const isComplete = (0, input_parser_1.isInputComplete)(query);
+        // Determine complexity
+        const complexity = this.determineComplexity(clauseCount, operatorCount, depth);
+        return {
+            depth,
+            clauseCount,
+            operatorCount,
+            hasBalancedParentheses,
+            hasBalancedQuotes,
+            isComplete,
+            referencedFields,
+            complexity
+        };
+    }
+    /**
+     * Calculate the maximum nesting depth of parentheses
+     */
+    calculateDepth(query) {
+        let maxDepth = 0;
+        let currentDepth = 0;
+        for (const char of query) {
+            if (char === '(') {
+                currentDepth++;
+                maxDepth = Math.max(maxDepth, currentDepth);
+            }
+            else if (char === ')') {
+                currentDepth = Math.max(0, currentDepth - 1);
+            }
+        }
+        // Base depth is 1 if there's any content
+        return query.trim().length > 0 ? Math.max(1, maxDepth) : 0;
+    }
+    /**
+     * Determine query complexity classification
+     */
+    determineComplexity(clauseCount, operatorCount, depth) {
+        // Simple: 1-2 clauses, no nesting
+        if (clauseCount <= 2 && depth <= 1) {
+            return 'simple';
+        }
+        // Complex: many clauses, deep nesting, or many operators
+        if (clauseCount > 5 || depth > 3 || operatorCount > 4) {
+            return 'complex';
+        }
+        return 'moderate';
+    }
+    /**
+     * Try to extract error position from error message
+     */
+    extractErrorPosition(errorMessage) {
+        // Try to find position indicators in error messages
+        // e.g., "at position 15" or "column 15"
+        const posMatch = errorMessage.match(/(?:position|column|offset)\s*(\d+)/i);
+        if (posMatch) {
+            return parseInt(posMatch[1], 10);
+        }
+        return undefined;
+    }
+    /**
+     * Try to extract the problematic text from the query based on error
+     */
+    extractProblematicText(query, errorMessage) {
+        // If we found a position, extract surrounding text
+        const position = this.extractErrorPosition(errorMessage);
+        if (position !== undefined && position < query.length) {
+            const start = Math.max(0, position - 10);
+            const end = Math.min(query.length, position + 10);
+            return query.substring(start, end);
+        }
+        // Try to find quoted text in error message
+        const quotedMatch = errorMessage.match(/"([^"]+)"/);
+        if (quotedMatch) {
+            return quotedMatch[1];
+        }
+        return undefined;
+    }
+    /**
+     * Validate fields against the provided schema
+     */
+    validateFields(referencedFields, schema) {
+        const schemaFields = Object.keys(schema);
+        const fields = [];
+        const unknownFields = [];
+        let allValid = true;
+        for (const field of referencedFields) {
+            if (field in schema) {
+                // Field exists in schema
+                fields.push({
+                    field,
+                    valid: true,
+                    expectedType: schema[field].type,
+                    allowedValues: schema[field].allowedValues
+                });
+            }
+            else {
+                // Field not in schema - try to find a suggestion
+                const suggestion = this.findSimilarField(field, schemaFields);
+                fields.push({
+                    field,
+                    valid: false,
+                    reason: 'unknown_field',
+                    suggestion
+                });
+                unknownFields.push(field);
+                allValid = false;
+            }
+        }
+        return {
+            valid: allValid,
+            fields,
+            unknownFields
+        };
+    }
+    /**
+     * Find a similar field name (for typo suggestions)
+     */
+    findSimilarField(field, schemaFields) {
+        const fieldLower = field.toLowerCase();
+        // First, try exact case-insensitive match
+        for (const schemaField of schemaFields) {
+            if (schemaField.toLowerCase() === fieldLower) {
+                return schemaField;
+            }
+        }
+        // Then, try to find fields that start with the same prefix
+        const prefix = fieldLower.substring(0, Math.min(3, fieldLower.length));
+        for (const schemaField of schemaFields) {
+            if (schemaField.toLowerCase().startsWith(prefix)) {
+                return schemaField;
+            }
+        }
+        // Try Levenshtein distance for short fields
+        if (field.length <= 10) {
+            let bestMatch;
+            let bestDistance = Infinity;
+            for (const schemaField of schemaFields) {
+                const distance = this.levenshteinDistance(fieldLower, schemaField.toLowerCase());
+                if (distance <= 2 && distance < bestDistance) {
+                    bestDistance = distance;
+                    bestMatch = schemaField;
+                }
+            }
+            if (bestMatch) {
+                return bestMatch;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Calculate Levenshtein distance between two strings
+     */
+    levenshteinDistance(a, b) {
+        const matrix = [];
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i];
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j;
+        }
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1];
+                }
+                else {
+                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                    matrix[i][j - 1] + 1, // insertion
+                    matrix[i - 1][j] + 1 // deletion
+                    );
+                }
+            }
+        }
+        return matrix[b.length][a.length];
+    }
+    /**
+     * Perform security pre-check against the provided options
+     */
+    performSecurityCheck(structure, options) {
+        const violations = [];
+        const warnings = [];
+        // Check denied fields
+        if (options.denyFields && options.denyFields.length > 0) {
+            for (const field of structure.referencedFields) {
+                if (options.denyFields.includes(field)) {
+                    violations.push({
+                        type: 'denied_field',
+                        message: `Field "${field}" is not allowed in queries`,
+                        field
+                    });
+                }
+            }
+        }
+        // Check allowed fields (if specified, only these fields are allowed)
+        if (options.allowedFields && options.allowedFields.length > 0) {
+            for (const field of structure.referencedFields) {
+                if (!options.allowedFields.includes(field)) {
+                    violations.push({
+                        type: 'field_not_allowed',
+                        message: `Field "${field}" is not in the list of allowed fields`,
+                        field
+                    });
+                }
+            }
+        }
+        // Check dot notation
+        if (options.allowDotNotation === false) {
+            for (const field of structure.referencedFields) {
+                if (field.includes('.')) {
+                    violations.push({
+                        type: 'dot_notation',
+                        message: `Dot notation is not allowed in field names: "${field}"`,
+                        field
+                    });
+                }
+            }
+        }
+        // Check query depth
+        if (options.maxQueryDepth !== undefined) {
+            if (structure.depth > options.maxQueryDepth) {
+                violations.push({
+                    type: 'depth_exceeded',
+                    message: `Query depth (${structure.depth}) exceeds maximum allowed (${options.maxQueryDepth})`
+                });
+            }
+            else if (structure.depth >= options.maxQueryDepth * 0.8) {
+                warnings.push({
+                    type: 'approaching_depth_limit',
+                    message: `Query depth (${structure.depth}) is approaching the limit (${options.maxQueryDepth})`,
+                    current: structure.depth,
+                    limit: options.maxQueryDepth
+                });
+            }
+        }
+        // Check clause count
+        if (options.maxClauseCount !== undefined) {
+            if (structure.clauseCount > options.maxClauseCount) {
+                violations.push({
+                    type: 'clause_limit',
+                    message: `Clause count (${structure.clauseCount}) exceeds maximum allowed (${options.maxClauseCount})`
+                });
+            }
+            else if (structure.clauseCount >= options.maxClauseCount * 0.8) {
+                warnings.push({
+                    type: 'approaching_clause_limit',
+                    message: `Clause count (${structure.clauseCount}) is approaching the limit (${options.maxClauseCount})`,
+                    current: structure.clauseCount,
+                    limit: options.maxClauseCount
+                });
+            }
+        }
+        // Add complexity warning
+        if (structure.complexity === 'complex') {
+            warnings.push({
+                type: 'complex_query',
+                message: 'This query is complex and may impact performance'
+            });
+        }
+        return {
+            passed: violations.length === 0,
+            violations,
+            warnings
+        };
+    }
+    /**
+     * Generate autocomplete suggestions based on cursor position
+     */
+    generateAutocompleteSuggestions(query, cursorPosition, activeToken, schema) {
+        // Determine context based on active token and position
+        if (!activeToken) {
+            // Cursor is not in a token - check if we're at the start or between tokens
+            if (query.trim().length === 0 || cursorPosition === 0) {
+                return this.suggestForEmptyContext(schema);
+            }
+            // Between tokens - suggest logical operators or new field
+            return this.suggestBetweenTokens(schema);
+        }
+        if (activeToken.type === 'operator') {
+            // Cursor is in a logical operator
+            return {
+                context: 'logical_operator',
+                logicalOperators: ['AND', 'OR', 'NOT'],
+                replaceText: activeToken.raw,
+                replaceRange: {
+                    start: activeToken.startPosition,
+                    end: activeToken.endPosition
+                }
+            };
+        }
+        // Active token is a term
+        const term = activeToken;
+        const relativePos = cursorPosition - term.startPosition;
+        // Determine if cursor is in key, operator, or value part
+        if (term.key !== null && term.operator !== null) {
+            const keyLength = term.key.length;
+            const operatorLength = term.operator.length;
+            if (relativePos < keyLength) {
+                // Cursor is in the field name
+                return this.suggestFields(term.key, schema);
+            }
+            else if (relativePos < keyLength + operatorLength) {
+                // Cursor is in the operator
+                return this.suggestOperators(term.key, schema);
+            }
+            else {
+                // Cursor is in the value
+                return this.suggestValues(term.key, term.value, schema);
+            }
+        }
+        else if (term.key !== null) {
+            // Only key present (incomplete)
+            return this.suggestFields(term.key, schema);
+        }
+        else {
+            // Bare value - could be a field name
+            return this.suggestFields(term.value || '', schema);
+        }
+    }
+    /**
+     * Suggest for empty/start context
+     */
+    suggestForEmptyContext(schema) {
+        return {
+            context: 'empty',
+            fields: this.getFieldSuggestions('', schema),
+            logicalOperators: ['NOT']
+        };
+    }
+    /**
+     * Suggest between tokens (after a complete term)
+     */
+    suggestBetweenTokens(schema) {
+        return {
+            context: 'logical_operator',
+            fields: this.getFieldSuggestions('', schema),
+            logicalOperators: ['AND', 'OR', 'NOT']
+        };
+    }
+    /**
+     * Suggest field names
+     */
+    suggestFields(partial, schema) {
+        return {
+            context: 'field',
+            fields: this.getFieldSuggestions(partial, schema),
+            replaceText: partial,
+            replaceRange: partial.length > 0 ? { start: 0, end: partial.length } : undefined
+        };
+    }
+    /**
+     * Get field suggestions based on partial input
+     */
+    getFieldSuggestions(partial, schema) {
+        if (!schema) {
+            return [];
+        }
+        const partialLower = partial.toLowerCase();
+        const suggestions = [];
+        for (const [field, fieldSchema] of Object.entries(schema)) {
+            const fieldLower = field.toLowerCase();
+            let score = 0;
+            if (partial.length === 0) {
+                // No partial - suggest all fields with base score
+                score = 50;
+            }
+            else if (fieldLower === partialLower) {
+                // Exact match
+                score = 100;
+            }
+            else if (fieldLower.startsWith(partialLower)) {
+                // Prefix match
+                score = 80 + (partial.length / field.length) * 20;
+            }
+            else if (fieldLower.includes(partialLower)) {
+                // Contains match
+                score = 60;
+            }
+            else {
+                // Check Levenshtein distance for typos
+                const distance = this.levenshteinDistance(partialLower, fieldLower);
+                if (distance <= 2) {
+                    score = 40 - distance * 10;
+                }
+            }
+            if (score > 0) {
+                suggestions.push({
+                    field,
+                    type: fieldSchema.type,
+                    description: fieldSchema.description,
+                    score
+                });
+            }
+        }
+        // Sort by score descending
+        return suggestions.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Suggest operators
+     */
+    suggestOperators(field, schema) {
+        const fieldType = schema?.[field]?.type;
+        const operators = this.getOperatorSuggestions(fieldType);
+        return {
+            context: 'operator',
+            currentField: field,
+            operators
+        };
+    }
+    /**
+     * Get operator suggestions based on field type
+     */
+    getOperatorSuggestions(fieldType) {
+        const allOperators = [
+            { operator: ':', description: 'equals', applicable: true },
+            { operator: ':!=', description: 'not equals', applicable: true },
+            {
+                operator: ':>',
+                description: 'greater than',
+                applicable: fieldType === 'number' || fieldType === 'date'
+            },
+            {
+                operator: ':>=',
+                description: 'greater than or equal',
+                applicable: fieldType === 'number' || fieldType === 'date'
+            },
+            {
+                operator: ':<',
+                description: 'less than',
+                applicable: fieldType === 'number' || fieldType === 'date'
+            },
+            {
+                operator: ':<=',
+                description: 'less than or equal',
+                applicable: fieldType === 'number' || fieldType === 'date'
+            }
+        ];
+        // Sort applicable operators first
+        return allOperators.sort((a, b) => {
+            if (a.applicable && !b.applicable)
+                return -1;
+            if (!a.applicable && b.applicable)
+                return 1;
+            return 0;
+        });
+    }
+    /**
+     * Suggest values
+     */
+    suggestValues(field, partialValue, schema) {
+        const fieldSchema = schema?.[field];
+        const values = this.getValueSuggestions(partialValue || '', fieldSchema);
+        return {
+            context: 'value',
+            currentField: field,
+            values,
+            replaceText: partialValue || undefined
+        };
+    }
+    /**
+     * Get value suggestions based on schema
+     */
+    getValueSuggestions(partial, fieldSchema) {
+        if (!fieldSchema?.allowedValues) {
+            // Suggest based on type
+            if (fieldSchema?.type === 'boolean') {
+                return [
+                    { value: true, label: 'true', score: 100 },
+                    { value: false, label: 'false', score: 100 }
+                ];
+            }
+            return [];
+        }
+        const partialLower = partial.toLowerCase();
+        const suggestions = [];
+        for (const value of fieldSchema.allowedValues) {
+            const valueStr = String(value).toLowerCase();
+            let score = 0;
+            if (partial.length === 0) {
+                score = 50;
+            }
+            else if (valueStr === partialLower) {
+                score = 100;
+            }
+            else if (valueStr.startsWith(partialLower)) {
+                score = 80;
+            }
+            else if (valueStr.includes(partialLower)) {
+                score = 60;
+            }
+            if (score > 0) {
+                suggestions.push({
+                    value,
+                    label: String(value),
+                    score
+                });
+            }
+        }
+        return suggestions.sort((a, b) => b.score - a.score);
+    }
+    /**
+     * Generate error recovery suggestions
+     */
+    generateErrorRecovery(query, structure) {
+        // Check for unclosed quotes
+        const singleQuotes = (query.match(/'/g) || []).length;
+        const doubleQuotes = (query.match(/"/g) || []).length;
+        if (singleQuotes % 2 !== 0) {
+            const lastQuotePos = query.lastIndexOf("'");
+            return {
+                issue: 'unclosed_quote',
+                message: 'Unclosed single quote detected',
+                suggestion: "Add a closing ' to complete the quoted value",
+                autofix: query + "'",
+                position: lastQuotePos
+            };
+        }
+        if (doubleQuotes % 2 !== 0) {
+            const lastQuotePos = query.lastIndexOf('"');
+            return {
+                issue: 'unclosed_quote',
+                message: 'Unclosed double quote detected',
+                suggestion: 'Add a closing " to complete the quoted value',
+                autofix: query + '"',
+                position: lastQuotePos
+            };
+        }
+        // Check for unbalanced parentheses
+        if (!structure.hasBalancedParentheses) {
+            const openCount = (query.match(/\(/g) || []).length;
+            const closeCount = (query.match(/\)/g) || []).length;
+            if (openCount > closeCount) {
+                return {
+                    issue: 'unclosed_parenthesis',
+                    message: `Missing ${openCount - closeCount} closing parenthesis`,
+                    suggestion: 'Add closing parenthesis to balance the expression',
+                    autofix: query + ')'.repeat(openCount - closeCount)
+                };
+            }
+            else {
+                return {
+                    issue: 'unclosed_parenthesis',
+                    message: `Extra ${closeCount - openCount} closing parenthesis`,
+                    suggestion: 'Remove extra closing parenthesis'
+                };
+            }
+        }
+        // Check for trailing operator
+        const trimmed = query.trim();
+        if (/\b(AND|OR|NOT)\s*$/i.test(trimmed)) {
+            const match = trimmed.match(/\b(AND|OR|NOT)\s*$/i);
+            return {
+                issue: 'trailing_operator',
+                message: `Query ends with incomplete "${match?.[1]}" operator`,
+                suggestion: 'Add a condition after the operator or remove it',
+                autofix: trimmed.replace(/\s*(AND|OR|NOT)\s*$/i, '').trim()
+            };
+        }
+        // Check for missing value (field:)
+        if (/:$/.test(trimmed) || /:\s*$/.test(trimmed)) {
+            return {
+                issue: 'missing_value',
+                message: 'Field is missing a value',
+                suggestion: 'Add a value after the colon'
+            };
+        }
+        // Generic syntax error
+        return {
+            issue: 'syntax_error',
+            message: 'Query contains a syntax error',
+            suggestion: 'Check the query syntax and try again'
+        };
+    }
 }
 exports.QueryParser = QueryParser;