@atomic-ehr/fhirpath 0.0.1-canary.0c6931e.20250727185306

package/src/parser/ast-factory.ts

@@ -0,0 +1,220 @@
+import type { Token } from '../lexer/token';
+import { TokenType } from '../lexer/token';
+import type { Position } from './ast';
+import {
+  type ASTNode,
+  type BinaryNode,
+  type UnaryNode,
+  type LiteralNode,
+  type IdentifierNode,
+  type TypeOrIdentifierNode,
+  type FunctionNode,
+  type VariableNode,
+  type IndexNode,
+  type UnionNode,
+  type MembershipTestNode,
+  type TypeCastNode,
+  type CollectionNode,
+  type TypeReferenceNode,
+  type ErrorNode,
+  type IncompleteNode,
+  NodeType
+} from './ast';
+import type { ParseDiagnostic as Diagnostic } from './types';
+import type { Operation } from '../registry/types';
+
+/**
+ * Factory for creating AST nodes with consistent structure
+ */
+export class ASTFactory {
+  static createLiteral(
+    value: any, 
+    valueType: 'string' | 'number' | 'boolean' | 'date' | 'time' | 'datetime' | 'null',
+    position: Position,
+    raw?: string,
+    operation?: Operation
+  ): LiteralNode {
+    return {
+      type: NodeType.Literal,
+      value,
+      valueType,
+      raw,
+      operation,
+      position
+    };
+  }
+
+  static createIdentifier(name: string, position: Position): IdentifierNode {
+    return {
+      type: NodeType.Identifier,
+      name,
+      position
+    };
+  }
+
+  static createTypeOrIdentifier(name: string, position: Position): TypeOrIdentifierNode {
+    return {
+      type: NodeType.TypeOrIdentifier,
+      name,
+      position
+    };
+  }
+
+  static createVariable(name: string, isSpecial: boolean, position: Position): VariableNode {
+    return {
+      type: NodeType.Variable,
+      name,
+      position
+    };
+  }
+
+  static createBinary(
+    operator: TokenType,
+    left: ASTNode,
+    right: ASTNode,
+    position: Position,
+    operation?: Operation
+  ): BinaryNode {
+    return {
+      type: NodeType.Binary,
+      operator,
+      operation,
+      left,
+      right,
+      position
+    };
+  }
+
+  static createUnary(
+    operator: TokenType,
+    operand: ASTNode,
+    position: Position,
+    operation?: Operation
+  ): UnaryNode {
+    return {
+      type: NodeType.Unary,
+      operator,
+      operation,
+      operand,
+      position
+    };
+  }
+
+  static createFunction(
+    name: ASTNode,
+    args: ASTNode[],
+    position: Position,
+    operation?: Operation
+  ): FunctionNode {
+    return {
+      type: NodeType.Function,
+      name,
+      arguments: args,
+      operation,
+      position
+    };
+  }
+
+  static createUnion(operands: ASTNode[], position: Position): UnionNode {
+    return {
+      type: NodeType.Union,
+      operands,
+      position
+    };
+  }
+
+  static createIndex(expression: ASTNode, index: ASTNode, position: Position): IndexNode {
+    return {
+      type: NodeType.Index,
+      expression,
+      index,
+      position
+    };
+  }
+
+  static createCollection(elements: ASTNode[], position: Position): CollectionNode {
+    return {
+      type: NodeType.Collection,
+      elements,
+      position
+    };
+  }
+
+  static createMembershipTest(
+    expression: ASTNode,
+    targetType: string,
+    position: Position
+  ): MembershipTestNode {
+    return {
+      type: NodeType.MembershipTest,
+      expression,
+      targetType,
+      position
+    };
+  }
+
+  static createTypeCast(
+    expression: ASTNode,
+    targetType: string,
+    position: Position
+  ): TypeCastNode {
+    return {
+      type: NodeType.TypeCast,
+      expression,
+      targetType,
+      position
+    };
+  }
+
+  static createTypeReference(name: string, position: Position): TypeReferenceNode {
+    return {
+      type: NodeType.TypeReference,
+      typeName: name,
+      position
+    };
+  }
+
+  static createError(
+    position: Position,
+    expectedTokens: TokenType[],
+    diagnostic: Diagnostic
+  ): ErrorNode {
+    return {
+      type: NodeType.Error,
+      position,
+      expectedTokens,
+      diagnostic
+    };
+  }
+
+  static createIncomplete(
+    partialNode: ASTNode | undefined,
+    missingParts: string[],
+    position: Position
+  ): IncompleteNode {
+    return {
+      type: NodeType.Incomplete,
+      partialNode,
+      missingParts,
+      position
+    };
+  }
+
+  /**
+   * Infer literal type from value
+   */
+  static inferLiteralType(value: any): 'string' | 'number' | 'boolean' | 'date' | 'time' | 'datetime' | 'null' {
+    if (value === null) return 'null';
+    if (typeof value === 'boolean') return 'boolean';
+    if (typeof value === 'number') return 'number';
+    if (typeof value === 'string') return 'string';
+    if (value instanceof Date) {
+      // Check if it has time component
+      const hasTime = value.getHours() !== 0 || value.getMinutes() !== 0 || value.getSeconds() !== 0;
+      return hasTime ? 'datetime' : 'date';
+    }
+    // Check for time-only values (stored as strings like "14:30:00")
+    if (typeof value === 'object' && value.type === 'time') return 'time';
+    return 'string'; // default
+  }
+}

package/src/parser/ast.ts

@@ -0,0 +1,144 @@
+import type { TokenType, Token } from '../lexer/token';
+import type { TextRange } from './types';
+import type { ParseDiagnostic } from './types';
+
+// Core AST Node Interface
+export interface ASTNode {
+  type: NodeType;
+  position: Position;
+  range?: TextRange;     // Full text range (populated in diagnostic modes)
+  // Type analysis fields (optional - added by analyzer)
+  resultType?: unknown;  // Opaque type reference
+  isSingleton?: boolean; // Whether this expression returns a single value
+}
+
+export interface Position {
+  line: number;
+  column: number;
+  offset: number;
+}
+
+// Node types
+export enum NodeType {
+  // Navigation
+  Identifier,
+  TypeOrIdentifier, // Uppercase identifiers that could be types (Patient, Observation)
+  
+  // Operators
+  Binary,     // All binary operators including dot
+  Unary,      // unary +, -, not
+  Union,      // | operator (special handling for multiple operands)
+  
+  // Functions
+  Function,   // Function calls
+  
+  // Literals
+  Literal,    // numbers, strings, booleans, dates, null
+  Variable,   // $this, $index, $total, %var
+  Collection, // {} empty collection or {expr1, expr2, ...}
+  
+  // Type operations
+  MembershipTest, // 'is' operator
+  TypeCast,       // 'as' operator
+  TypeReference,  // Type name in ofType()
+  
+  // Special
+  Index,      // [] indexing
+  
+  // Error recovery
+  Error = 'Error',           // Error recovery node
+  Incomplete = 'Incomplete'  // Incomplete expression node
+}
+
+// Specific node types
+export interface IdentifierNode extends ASTNode {
+  type: NodeType.Identifier;
+  name: string;
+}
+
+export interface TypeOrIdentifierNode extends ASTNode {
+  type: NodeType.TypeOrIdentifier;
+  name: string;
+}
+
+export interface LiteralNode extends ASTNode {
+  type: NodeType.Literal;
+  value: any;
+  valueType: 'string' | 'number' | 'boolean' | 'date' | 'time' | 'datetime' | 'null';
+  raw?: string;        // Raw string representation
+  operation?: any;     // Operation from registry (using any to avoid circular dependency)
+}
+
+export interface BinaryNode extends ASTNode {
+  type: NodeType.Binary;
+  operator: TokenType;
+  operation?: any;     // Operation from registry (using any to avoid circular dependency)
+  left: ASTNode;
+  right: ASTNode;
+}
+
+export interface UnaryNode extends ASTNode {
+  type: NodeType.Unary;
+  operator: TokenType;
+  operation?: any;     // Operation from registry (using any to avoid circular dependency)
+  operand: ASTNode;
+}
+
+export interface FunctionNode extends ASTNode {
+  type: NodeType.Function;
+  name: ASTNode;  // Usually an identifier
+  arguments: ASTNode[];
+  operation?: any;     // Operation from registry (using any to avoid circular dependency)
+}
+
+export interface VariableNode extends ASTNode {
+  type: NodeType.Variable;
+  name: string;
+}
+
+export interface IndexNode extends ASTNode {
+  type: NodeType.Index;
+  expression: ASTNode;
+  index: ASTNode;
+}
+
+export interface UnionNode extends ASTNode {
+  type: NodeType.Union;
+  operands: ASTNode[];
+}
+
+export interface MembershipTestNode extends ASTNode {
+  type: NodeType.MembershipTest;
+  expression: ASTNode;
+  targetType: string;
+}
+
+export interface TypeCastNode extends ASTNode {
+  type: NodeType.TypeCast;
+  expression: ASTNode;
+  targetType: string;
+}
+
+export interface CollectionNode extends ASTNode {
+  type: NodeType.Collection;
+  elements: ASTNode[];
+}
+
+export interface TypeReferenceNode extends ASTNode {
+  type: NodeType.TypeReference;
+  typeName: string;
+}
+
+// Error recovery nodes
+export interface ErrorNode extends ASTNode {
+  type: NodeType.Error;
+  expectedTokens?: TokenType[];
+  actualToken?: Token;
+  diagnostic: ParseDiagnostic;
+}
+
+export interface IncompleteNode extends ASTNode {
+  type: NodeType.Incomplete;
+  partialNode?: ASTNode;
+  missingParts: string[];
+}

package/src/parser/collection-parser.ts

@@ -0,0 +1,89 @@
+import type { Token } from '../lexer/token';
+import { TokenType } from '../lexer/token';
+import type { ASTNode } from './ast';
+import { ASTFactory } from './ast-factory';
+import type { TokenNavigator } from './token-navigator';
+import { ParseError } from './parse-error';
+import { ErrorCode } from '../api/errors';
+
+/**
+ * Handles parsing of collections and parenthesized expressions
+ */
+export class CollectionParser {
+  /**
+   * Parse collection literal {...}
+   */
+  static parseCollection(
+    navigator: TokenNavigator,
+    parseExpression: () => ASTNode,
+    errorCallback: (msg: string, code?: ErrorCode) => ParseError,
+    errorRecovery: boolean,
+    createErrorNode: (token: Token, msg: string) => ASTNode
+  ): ASTNode {
+    const lbrace = navigator.previous();
+    const elements: ASTNode[] = [];
+    
+    // Empty collection
+    if (navigator.match(TokenType.RBRACE)) {
+      return ASTFactory.createCollection([], lbrace.position);
+    }
+    
+    // Parse elements
+    do {
+      // Check for trailing comma
+      if (navigator.check(TokenType.RBRACE)) {
+        break;
+      }
+      
+      try {
+        elements.push(parseExpression());
+      } catch (error) {
+        if (error instanceof ParseError && errorRecovery) {
+          elements.push(createErrorNode(error.token, error.message));
+          // Skip to next comma or closing brace
+          navigator.skipWhile(token => 
+            token.type !== TokenType.COMMA && 
+            token.type !== TokenType.RBRACE
+          );
+        } else {
+          throw error;
+        }
+      }
+    } while (navigator.match(TokenType.COMMA));
+    
+    // Check for trailing comma error
+    if (elements.length > 0 && navigator.previous().type === TokenType.COMMA) {
+      throw errorCallback("Expected expression after ','", ErrorCode.EXPECTED_EXPRESSION);
+    }
+    
+    navigator.consume(TokenType.RBRACE, () => 
+      errorCallback("Expected '}' after collection elements", ErrorCode.UNCLOSED_BRACE)
+    );
+    
+    return ASTFactory.createCollection(elements, lbrace.position);
+  }
+  
+  /**
+   * Parse parenthesized expression
+   */
+  static parseParenthesized(
+    navigator: TokenNavigator,
+    parseExpression: () => ASTNode,
+    errorCallback: (msg: string, code?: ErrorCode) => ParseError
+  ): ASTNode {
+    const lparen = navigator.previous();
+    
+    // Handle empty parentheses ()
+    if (navigator.check(TokenType.RPAREN)) {
+      throw errorCallback("Empty parentheses are not allowed", ErrorCode.EXPECTED_EXPRESSION);
+    }
+    
+    const expr = parseExpression();
+    
+    navigator.consume(TokenType.RPAREN, () => 
+      errorCallback("Expected ')' after expression", ErrorCode.UNCLOSED_PARENTHESIS)
+    );
+    
+    return expr;
+  }
+}

package/src/parser/diagnostic-messages.ts

@@ -0,0 +1,216 @@
+import type { Token } from '../lexer/token';
+import type { SourceMapper } from './source-mapper';
+import type { ParseDiagnostic, TextRange, RelatedInformation } from './types';
+import type { FunctionNode } from './ast';
+import { ErrorCode } from '../api/errors';
+import { DiagnosticSeverity } from './types';
+
+/**
+ * Factory for creating common FHIRPath diagnostic messages
+ */
+export class FHIRPathDiagnostics {
+  static unclosedParenthesis(openParen: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(openParen);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.UNCLOSED_PARENTHESIS,
+      message: "Unclosed parenthesis - missing ')' to close function call",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static unclosedBracket(openBracket: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(openBracket);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.UNCLOSED_BRACKET,
+      message: "Expected ']' after index expression",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static unclosedBrace(openBrace: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(openBrace);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.UNCLOSED_BRACE,
+      message: "Expected '}' to close collection literal",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static missingFunctionArguments(
+    functionName: string,
+    position: TextRange,
+    functionDefinitionLocation?: TextRange
+  ): ParseDiagnostic {
+    const diagnostic: ParseDiagnostic = {
+      range: position,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.MISSING_ARGUMENTS,
+      message: `Function '${functionName}' requires arguments`,
+      source: 'fhirpath-parser'
+    };
+    
+    if (functionDefinitionLocation) {
+      diagnostic.relatedInformation = [{
+        location: functionDefinitionLocation,
+        message: `Function '${functionName}' defined here`
+      }];
+    }
+    
+    return diagnostic;
+  }
+  
+  static doubleDotOperator(firstDot: Token, secondDot: Token, mapper: SourceMapper): ParseDiagnostic {
+    const startPos = mapper.tokenToRange(firstDot).start;
+    const endPos = mapper.tokenToRange(secondDot).end;
+    const range: TextRange = { start: startPos, end: endPos };
+    
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.INVALID_OPERATOR,
+      message: "Invalid '..' operator - use single '.' for navigation",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static unexpectedToken(
+    token: Token,
+    expected: string[],
+    mapper: SourceMapper
+  ): ParseDiagnostic {
+    const range = mapper.tokenToRange(token);
+    const expectedText = expected.length === 1 
+      ? expected[0]
+      : expected.slice(0, -1).join(', ') + ' or ' + expected[expected.length - 1];
+    
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.UNEXPECTED_TOKEN,
+      message: `Expected ${expectedText}, found '${token.value}'`,
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static invalidEscapeSequence(
+    escapeToken: Token,
+    escapeSequence: string,
+    mapper: SourceMapper
+  ): ParseDiagnostic {
+    const range = mapper.tokenToRange(escapeToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.INVALID_ESCAPE,
+      message: `Invalid escape sequence '${escapeSequence}'`,
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static unterminatedString(stringStart: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(stringStart);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.UNTERMINATED_STRING,
+      message: "Unterminated string literal",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static invalidCharacter(position: TextRange, character: string): ParseDiagnostic {
+    return {
+      range: position,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.INVALID_CHARACTER,
+      message: `Invalid character '${character}'`,
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static trailingComma(commaToken: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(commaToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_EXPRESSION,
+      message: "Expected expression after ','",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static missingOperand(
+    operatorToken: Token,
+    side: 'left' | 'right',
+    mapper: SourceMapper
+  ): ParseDiagnostic {
+    const range = mapper.tokenToRange(operatorToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_EXPRESSION,
+      message: `Expected expression ${side === 'left' ? 'before' : 'after'} '${operatorToken.value}'`,
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static emptyBrackets(openBracket: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(openBracket);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_EXPRESSION,
+      message: "Expected expression in index",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static spaceInDotNavigation(dotToken: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(dotToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_IDENTIFIER,
+      message: "Expected property name immediately after '.'",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static incompleteTypeCast(asToken: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(asToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_IDENTIFIER,
+      message: "Expected type name after 'as'",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static incompleteMembershipTest(isToken: Token, mapper: SourceMapper): ParseDiagnostic {
+    const range = mapper.tokenToRange(isToken);
+    return {
+      range,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.EXPECTED_IDENTIFIER,
+      message: "Expected type name after 'is'",
+      source: 'fhirpath-parser'
+    };
+  }
+  
+  static multipleErrors(errorCount: number, position: TextRange): ParseDiagnostic {
+    return {
+      range: position,
+      severity: DiagnosticSeverity.Error,
+      code: ErrorCode.MULTIPLE_ERRORS,
+      message: `Expression contains ${errorCount} errors`,
+      source: 'fhirpath-parser'
+    };
+  }
+}