@atomic-ehr/fhirpath 0.0.1 → 0.0.2-canary.261bb9b.20250811212042

package/src/cursor-nodes.ts

@@ -0,0 +1,111 @@
+export enum CursorContext {
+  Operator = 'operator',
+  Identifier = 'identifier',
+  Argument = 'argument',
+  Index = 'index',
+  Type = 'type',
+}
+
+export interface CursorNode {
+  type: 'CursorNode';
+  context: CursorContext;
+  position: number;
+  range: {
+    start: { line: number; character: number; offset: number };
+    end: { line: number; character: number; offset: number };
+  };
+}
+
+export interface CursorOperatorNode extends CursorNode {
+  context: CursorContext.Operator;
+}
+
+export interface CursorIdentifierNode extends CursorNode {
+  context: CursorContext.Identifier;
+}
+
+export interface CursorArgumentNode extends CursorNode {
+  context: CursorContext.Argument;
+  functionName: string;
+  argumentIndex: number;
+}
+
+export interface CursorIndexNode extends CursorNode {
+  context: CursorContext.Index;
+}
+
+export interface CursorTypeNode extends CursorNode {
+  context: CursorContext.Type;
+  typeOperator: 'is' | 'as' | 'ofType';
+}
+
+export type AnyCursorNode = 
+  | CursorOperatorNode
+  | CursorIdentifierNode
+  | CursorArgumentNode
+  | CursorIndexNode
+  | CursorTypeNode;
+
+export function isCursorNode(node: any): node is CursorNode {
+  return node && node.type === 'CursorNode';
+}
+
+export function createCursorOperatorNode(position: number): CursorOperatorNode {
+  const point = { line: 0, character: position, offset: position };
+  return {
+    type: 'CursorNode',
+    context: CursorContext.Operator,
+    position,
+    range: { start: point, end: point },
+  };
+}
+
+export function createCursorIdentifierNode(position: number): CursorIdentifierNode {
+  const point = { line: 0, character: position, offset: position };
+  return {
+    type: 'CursorNode',
+    context: CursorContext.Identifier,
+    position,
+    range: { start: point, end: point },
+  };
+}
+
+export function createCursorArgumentNode(
+  position: number,
+  functionName: string,
+  argumentIndex: number
+): CursorArgumentNode {
+  const point = { line: 0, character: position, offset: position };
+  return {
+    type: 'CursorNode',
+    context: CursorContext.Argument,
+    position,
+    functionName,
+    argumentIndex,
+    range: { start: point, end: point },
+  };
+}
+
+export function createCursorIndexNode(position: number): CursorIndexNode {
+  const point = { line: 0, character: position, offset: position };
+  return {
+    type: 'CursorNode',
+    context: CursorContext.Index,
+    position,
+    range: { start: point, end: point },
+  };
+}
+
+export function createCursorTypeNode(
+  position: number,
+  typeOperator: 'is' | 'as' | 'ofType'
+): CursorTypeNode {
+  const point = { line: 0, character: position, offset: position };
+  return {
+    type: 'CursorNode',
+    context: CursorContext.Type,
+    position,
+    typeOperator,
+    range: { start: point, end: point },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,247 @@
+import type { Range, Diagnostic } from './types';
+import { DiagnosticSeverity } from './types';
+
+/**
+ * Base error class for all FHIRPath errors
+ */
+export class FHIRPathError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public location?: Range
+  ) {
+    super(message);
+    this.name = 'FHIRPathError';
+    
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Convert FHIRPathError to Diagnostic for analyzer
+ */
+export function toDiagnostic(error: FHIRPathError, severity: DiagnosticSeverity = DiagnosticSeverity.Error): Diagnostic {
+  return {
+    code: error.code,
+    message: error.message,
+    severity,
+    range: error.location!,
+    source: 'fhirpath'
+  };
+}
+
+/**
+ * Error factory with specialized constructors
+ */
+export const Errors = {
+  // Resolution errors (1000-1999)
+  unknownOperator(operator: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_OPERATOR, `Unknown operator: ${operator}`, location);
+  },
+  
+  unknownFunction(name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_FUNCTION, `Unknown function: ${name}`, location);
+  },
+  
+  unknownVariable(name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_VARIABLE, `Unknown variable: ${name}`, location);
+  },
+  
+  unknownUserVariable(name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_USER_VARIABLE, `Unknown user variable: ${name}`, location);
+  },
+  
+  unknownProperty(property: string, type: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_PROPERTY, `Unknown property '${property}' on type ${type}`, location);
+  },
+  
+  unknownNodeType(nodeType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNKNOWN_NODE_TYPE, `Unknown node type: ${nodeType}`, location);
+  },
+  
+  noEvaluatorFound(evaluatorType: string, name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.NO_EVALUATOR_FOUND, `No evaluator found for ${evaluatorType}: ${name}`, location);
+  },
+  
+  variableNotDefined(name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.VARIABLE_NOT_DEFINED, `Variable '${name}' is not defined in the current scope`, location);
+  },
+  
+  // Arity errors (2000-2999)
+  wrongArgumentCount(funcName: string, expected: number, actual: number, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.WRONG_ARGUMENT_COUNT, `${funcName} expects ${expected} arguments, got ${actual}`, location);
+  },
+  
+  wrongArgumentCountRange(funcName: string, min: number, max: number, actual: number, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.WRONG_ARGUMENT_COUNT_RANGE, `${funcName} expects ${min} to ${max} arguments, got ${actual}`, location);
+  },
+  
+  singletonRequired(funcName: string, actualCount: number, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.SINGLETON_REQUIRED, `${funcName} requires a single item, but collection has ${actualCount} items`, location);
+  },
+  
+  stringSingletonRequired(funcName: string, actualCount: number, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.SINGLETON_REQUIRED, `${funcName} can only be used on a single string, but collection has ${actualCount} items`, location);
+  },
+  
+  emptyNotAllowed(funcName: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.EMPTY_NOT_ALLOWED, `${funcName} cannot operate on empty collection`, location);
+  },
+  
+  argumentRequired(funcName: string, argumentName: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.ARGUMENT_REQUIRED, `${funcName} requires ${argumentName}`, location);
+  },
+  
+  singletonTypeRequired(funcName: string, actualType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.SINGLETON_REQUIRED, `${funcName} expects a singleton value, but received collection type ${actualType}`, location);
+  },
+  
+  // Type errors (3000-3999)
+  
+  operatorTypeMismatch(operator: string, leftType: string, rightType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.OPERATOR_TYPE_MISMATCH, `Operator '${operator}' cannot be applied to types ${leftType} and ${rightType}`, location);
+  },
+  
+  argumentTypeMismatch(argIndex: number, funcName: string, expected: string, actual: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.ARGUMENT_TYPE_MISMATCH, `Argument ${argIndex} of ${funcName}: expected ${expected}, got ${actual}`, location);
+  },
+  
+  conversionFailed(value: string, targetType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.CONVERSION_FAILED, `Cannot convert '${value}' to ${targetType}`, location);
+  },
+  
+  invalidValueType(expected: string, actual: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_VALUE_TYPE, `${expected} expected, got ${actual}`, location);
+  },
+  
+  invalidOperandType(operation: string, type: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_OPERAND_TYPE, `Cannot apply ${operation} to ${type}`, location);
+  },
+  
+  stringOperationOnNonString(operation: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.STRING_OPERATION_ON_NON_STRING, `${operation} can only be used on string values`, location);
+  },
+  
+  numericOperationOnNonNumeric(operation: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.NUMERIC_OPERATION_ON_NON_NUMERIC, `${operation} can only be applied to numeric values`, location);
+  },
+  
+  booleanOperationOnNonBoolean(operation: string, index: number, actualType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.BOOLEAN_OPERATION_ON_NON_BOOLEAN, `${operation} expects all items to be Boolean values, but item at index ${index} is ${actualType}`, location);
+  },
+  
+  // Configuration errors (4000-4999)
+  modelProviderRequired(operation: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.MODEL_PROVIDER_REQUIRED, 
+      `ModelProvider required for '${operation}' operation. Even primitive types like Boolean can fail due to choice types (e.g., Patient.deceased is actually deceasedBoolean in FHIR data)`, 
+      location);
+  },
+  
+  // Syntax errors (5000-5999)
+  unexpectedToken(token: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.UNEXPECTED_TOKEN, `Unexpected token: ${token}`, location);
+  },
+  
+  expectedToken(expected: string, actual: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.EXPECTED_TOKEN, `Expected ${expected}, got ${actual}`, location);
+  },
+  
+  invalidSyntax(details: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_SYNTAX, `Invalid syntax: ${details}`, location);
+  },
+  
+  expectedIdentifier(after: string, actual: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.EXPECTED_IDENTIFIER, `Expected identifier after '${after}', got: ${actual}`, location);
+  },
+  
+  expectedTypeName(actual: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.EXPECTED_TYPE_NAME, `Expected type name, got: ${actual}`, location);
+  },
+  
+  // Domain errors (6000-6999)
+  divisionByZero(location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.DIVISION_BY_ZERO, 'Division by zero', location);
+  },
+  
+  invalidDateTimeFormat(format: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_DATE_TIME_FORMAT, `Invalid date/time format: '${format}'`, location);
+  },
+  
+  incompatibleUnits(unit1: string, unit2: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INCOMPATIBLE_UNITS, `Cannot perform operation on incompatible units: ${unit1} and ${unit2}`, location);
+  },
+  
+  indexOutOfBounds(index: number, size: number, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INDEX_OUT_OF_BOUNDS, `Index ${index} out of bounds for collection of size ${size}`, location);
+  },
+  
+  invalidOperation(details: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_OPERATION, `Invalid operation: ${details}`, location);
+  },
+  
+  invalidPrecision(operation: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_PRECISION, `${operation} precision must be a non-negative integer`, location);
+  },
+  
+  invalidStringOperation(operation: string, paramName: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_STRING_OPERATION, `${operation} ${paramName} must be a string`, location);
+  },
+  
+  invalidNumericOperation(operation: string, paramName: string, expectedType: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_NUMERIC_OPERATION, `${operation} ${paramName} must be ${expectedType}`, location);
+  }
+};
+
+// Export error codes as enum for external use
+export enum ErrorCodes {
+  // Resolution errors (1000-1999)
+  UNKNOWN_OPERATOR = 'FP1001',
+  UNKNOWN_FUNCTION = 'FP1002',
+  UNKNOWN_VARIABLE = 'FP1003',
+  UNKNOWN_USER_VARIABLE = 'FP1004',
+  UNKNOWN_PROPERTY = 'FP1005',
+  UNKNOWN_NODE_TYPE = 'FP1006',
+  NO_EVALUATOR_FOUND = 'FP1007',
+  VARIABLE_NOT_DEFINED = 'FP1008',
+  
+  // Arity errors (2000-2999)
+  WRONG_ARGUMENT_COUNT = 'FP2001',
+  WRONG_ARGUMENT_COUNT_RANGE = 'FP2002',
+  SINGLETON_REQUIRED = 'FP2003',
+  EMPTY_NOT_ALLOWED = 'FP2004',
+  ARGUMENT_REQUIRED = 'FP2005',
+  
+  // Type errors (3000-3999)
+  // FP3001 - removed (unified with FP3006)
+  OPERATOR_TYPE_MISMATCH = 'FP3002',
+  ARGUMENT_TYPE_MISMATCH = 'FP3003',
+  CONVERSION_FAILED = 'FP3004',
+  INVALID_VALUE_TYPE = 'FP3005',
+  INVALID_OPERAND_TYPE = 'FP3006',
+  STRING_OPERATION_ON_NON_STRING = 'FP3007',
+  NUMERIC_OPERATION_ON_NON_NUMERIC = 'FP3008',
+  BOOLEAN_OPERATION_ON_NON_BOOLEAN = 'FP3009',
+  
+  // Configuration errors (4000-4999)
+  MODEL_PROVIDER_REQUIRED = 'FP4001',
+  
+  // Syntax errors (5000-5999)
+  UNEXPECTED_TOKEN = 'FP5001',
+  EXPECTED_TOKEN = 'FP5002',
+  INVALID_SYNTAX = 'FP5003',
+  EXPECTED_IDENTIFIER = 'FP5004',
+  EXPECTED_TYPE_NAME = 'FP5005',
+  
+  // Domain errors (6000-6999)
+  DIVISION_BY_ZERO = 'FP6001',
+  INVALID_DATE_TIME_FORMAT = 'FP6002',
+  INCOMPATIBLE_UNITS = 'FP6003',
+  INDEX_OUT_OF_BOUNDS = 'FP6004',
+  INVALID_OPERATION = 'FP6005',
+  INVALID_PRECISION = 'FP6006',
+  INVALID_STRING_OPERATION = 'FP6007',
+  INVALID_NUMERIC_OPERATION = 'FP6008'
+}

package/src/index.ts

@@ -2,16 +2,20 @@ import { Parser } from './parser';
 import { Interpreter, RuntimeContextManager } from './interpreter';
 import { Analyzer } from './analyzer';
 import type { AnalysisResult } from './types';
+import { box, unbox } from './boxing';
+import { FHIRPathError, Errors } from './errors';
 
 export interface EvaluateOptions {
   input?: unknown;
   variables?: Record<string, unknown>;
+  modelProvider?: import('./types').ModelProvider;
+  inputType?: import('./types').TypeInfo;
 }
 
-export function evaluate(
+export async function evaluate(
   expression: string,
   options: EvaluateOptions = {}
-): any[] {
+): Promise<any[]> {
   const parser = new Parser(expression);
   const parseResult = parser.parse();
   
@@ -19,19 +23,60 @@ export function evaluate(
   if (parseResult.errors.length > 0) {
     // For backward compatibility, throw the first error
     const firstError = parseResult.errors[0]!;
-    throw new Error(firstError.message);
+    throw Errors.invalidSyntax(firstError.message);
   }
   
-  const ast = parseResult.ast;
+  // ALWAYS analyze the AST
+  const analyzer = new Analyzer(options.modelProvider);
+  const analysisResult = await analyzer.analyze(
+    parseResult.ast, 
+    options.variables,
+    options.inputType
+  );
   
-  const interpreter = new Interpreter();
+  // Check for analysis errors
+  const errors = analysisResult.diagnostics.filter(d => d.severity === 1); // DiagnosticSeverity.Error
+  if (errors.length > 0) {
+    // Throw the first error
+    const firstError = errors[0]!;
+    if (firstError.code) {
+      // Always throw as FHIRPathError if we have a code
+      throw new FHIRPathError(firstError.code, firstError.message, firstError.range);
+    } else {
+      // Otherwise throw a generic error
+      throw new Error(firstError.message);
+    }
+  }
+  
+  // Use the analyzed AST with type information
+  const interpreter = new Interpreter(undefined, options.modelProvider);
   const input = options.input === undefined ? [] : Array.isArray(options.input) ? options.input : [options.input];
   
+  // Box input with typeInfo if we have a modelProvider and the input is a FHIR resource
+  let boxedInput = input;
+  if (options.modelProvider) {
+    boxedInput = await Promise.all(input.map(async item => {
+      if (item && typeof item === 'object' && 'resourceType' in item && typeof item.resourceType === 'string') {
+        // Get type info asynchronously
+        const typeInfo = await options.modelProvider!.getType(item.resourceType);
+        if (typeInfo) {
+          return box(item, typeInfo);
+        }
+      }
+      return item;
+    }));
+  }
+  
   // Create context with variables if provided
   let context = RuntimeContextManager.create(input);
   
-  // Set $this to the input (required for expressions like $this.where(...))
-  context = RuntimeContextManager.setVariable(context, '$this', input);
+  // Set $this to the boxed input (required for expressions like $this.where(...))
+  context = RuntimeContextManager.setVariable(context, '$this', boxedInput);
+  
+  // Add model provider to context if available
+  if (options.modelProvider) {
+    context.modelProvider = options.modelProvider;
+  }
   
   if (options.variables) {
     for (const [key, value] of Object.entries(options.variables)) {
@@ -40,12 +85,13 @@ export function evaluate(
     }
   }
   
-  const result = interpreter.evaluate(ast, input, context);
+  const result = await interpreter.evaluate(analysisResult.ast, input, context);
   
-  return result.value;
+  // Unbox the results before returning
+  return result.value.map(unbox);
 }
 
-export function analyze(
+export async function analyze(
   expression: string,
   options: { 
     variables?: Record<string, unknown>;
@@ -53,7 +99,7 @@ export function analyze(
     inputType?: import('./types').TypeInfo;
     errorRecovery?: boolean;
   } = {}
-): AnalysisResult {
+): Promise<AnalysisResult> {
   // Use LSP mode with error recovery if requested
   const parserOptions = options.errorRecovery 
     ? { mode: 'lsp' as const, errorRecovery: true }
@@ -66,14 +112,14 @@ export function analyze(
   if (!options.errorRecovery && parseResult.errors.length > 0) {
     // For backward compatibility, throw the first error
     const firstError = parseResult.errors[0]!;
-    throw new Error(firstError.message);
+    throw Errors.invalidSyntax(firstError.message);
   }
   
   const ast = parseResult.ast;
   
   // Create analyzer with optional model provider
   const analyzer = new Analyzer(options.modelProvider);
-  const analysisResult = analyzer.analyze(ast, options.variables, options.inputType);
+  const analysisResult = await analyzer.analyze(ast, options.variables, options.inputType);
   
   // If error recovery is enabled, merge parse errors into diagnostics
   if (options.errorRecovery && parseResult.errors.length > 0) {
@@ -109,4 +155,41 @@ export type { FHIRModelContext, FHIRModelProviderConfig } from './model-provider
 
 // Export inspect API
 export { inspect } from './inspect';
-export type { InspectOptions, InspectResult, TraceEntry } from './inspect';
+export type { InspectOptions, InspectResult, ASTMetadata } from './inspect';
+
+// Export error system
+export { FHIRPathError, Errors, ErrorCodes } from './errors';
+
+// Export LSP support - completion provider and cursor nodes
+/**
+ * Provides context-aware code completions for FHIRPath expressions.
+ * @param expression - The FHIRPath expression being edited
+ * @param cursorPosition - The cursor position (0-based offset)
+ * @param options - Optional configuration including modelProvider and variables
+ * @returns Array of completion items with labels, kinds, and documentation
+ * 
+ * @example
+ * ```typescript
+ * import { provideCompletions } from 'fhirpath';
+ * 
+ * const completions = provideCompletions('Patient.', 8);
+ * // Returns completions for properties and functions after 'Patient.'
+ * ```
+ */
+export { provideCompletions, CompletionKind } from './completion-provider';
+export type { 
+  CompletionItem, 
+  CompletionOptions
+} from './completion-provider';
+
+// Export cursor node types for LSP integration
+export { CursorContext, isCursorNode } from './cursor-nodes';
+export type {
+  CursorNode,
+  CursorOperatorNode,
+  CursorIdentifierNode,
+  CursorArgumentNode,
+  CursorIndexNode,
+  CursorTypeNode,
+  AnyCursorNode
+} from './cursor-nodes';