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

package/src/api/errors.ts

@@ -0,0 +1,145 @@
+import type { Location } from './types';
+
+export enum ErrorCode {
+  // Parse errors
+  PARSE_ERROR = 'PARSE_ERROR',
+  SYNTAX_ERROR = 'SYNTAX_ERROR',
+  UNEXPECTED_TOKEN = 'UNEXPECTED_TOKEN',
+  UNTERMINATED_STRING = 'UNTERMINATED_STRING',
+  INVALID_ESCAPE = 'INVALID_ESCAPE',
+  
+  // Parser-specific error codes
+  UNCLOSED_PARENTHESIS = 'UNCLOSED_PARENTHESIS',
+  UNCLOSED_BRACKET = 'UNCLOSED_BRACKET',
+  UNCLOSED_BRACE = 'UNCLOSED_BRACE',
+  MISSING_ARGUMENTS = 'MISSING_ARGUMENTS',
+  INVALID_OPERATOR = 'INVALID_OPERATOR',
+  EXPECTED_EXPRESSION = 'EXPECTED_EXPRESSION',
+  EXPECTED_IDENTIFIER = 'EXPECTED_IDENTIFIER',
+  MULTIPLE_ERRORS = 'MULTIPLE_ERRORS',
+  INVALID_CHARACTER = 'INVALID_CHARACTER',
+  
+  // Type errors
+  TYPE_ERROR = 'TYPE_ERROR',
+  TYPE_MISMATCH = 'TYPE_MISMATCH',
+  UNKNOWN_TYPE = 'UNKNOWN_TYPE',
+  CARDINALITY_ERROR = 'CARDINALITY_ERROR',
+  
+  // Runtime errors
+  RUNTIME_ERROR = 'RUNTIME_ERROR',
+  UNDEFINED_VARIABLE = 'UNDEFINED_VARIABLE',
+  UNDEFINED_FUNCTION = 'UNDEFINED_FUNCTION',
+  INVALID_ARGUMENT = 'INVALID_ARGUMENT',
+  DIVISION_BY_ZERO = 'DIVISION_BY_ZERO',
+  
+  // Analysis errors
+  ANALYSIS_ERROR = 'ANALYSIS_ERROR',
+  UNREACHABLE_CODE = 'UNREACHABLE_CODE',
+  AMBIGUOUS_TYPE = 'AMBIGUOUS_TYPE',
+}
+
+export class FHIRPathError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode,
+    public location?: Location,
+    public expression?: string
+  ) {
+    super(message);
+    this.name = 'FHIRPathError';
+    
+    // Ensure proper prototype chain
+    Object.setPrototypeOf(this, FHIRPathError.prototype);
+  }
+  
+  override toString(): string {
+    let result = `${this.name}: ${this.message}`;
+    
+    if (this.expression && this.location) {
+      result += `\n\n${this.expression}`;
+      if (this.location.offset >= 0 && this.location.length > 0) {
+        const indent = ' '.repeat(this.location.offset);
+        const marker = '^'.repeat(this.location.length);
+        result += `\n${indent}${marker}`;
+      }
+    }
+    
+    if (this.location) {
+      result += `\n\nAt line ${this.location.line}, column ${this.location.column}`;
+    }
+    
+    return result;
+  }
+}
+
+// Error factory functions
+export function parseError(
+  message: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(message, ErrorCode.PARSE_ERROR, location, expression);
+}
+
+export function syntaxError(
+  message: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(message, ErrorCode.SYNTAX_ERROR, location, expression);
+}
+
+export function typeError(
+  message: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(message, ErrorCode.TYPE_ERROR, location, expression);
+}
+
+export function runtimeError(
+  message: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(message, ErrorCode.RUNTIME_ERROR, location, expression);
+}
+
+export function undefinedVariable(
+  name: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(
+    `Undefined variable: ${name}`,
+    ErrorCode.UNDEFINED_VARIABLE,
+    location,
+    expression
+  );
+}
+
+export function undefinedFunction(
+  name: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(
+    `Undefined function: ${name}`,
+    ErrorCode.UNDEFINED_FUNCTION,
+    location,
+    expression
+  );
+}
+
+export function invalidArgument(
+  message: string,
+  location?: Location,
+  expression?: string
+): FHIRPathError {
+  return new FHIRPathError(
+    `Invalid argument: ${message}`,
+    ErrorCode.INVALID_ARGUMENT,
+    location,
+    expression
+  );
+}

package/src/api/expression.ts

@@ -0,0 +1,156 @@
+import type { ASTNode } from '../parser/ast';
+import type { 
+  FHIRPathExpression as IFHIRPathExpression,
+  CompiledExpression,
+  EvaluationContext,
+  CompileOptions,
+  AnalyzeOptions,
+  AnalysisResult
+} from './types';
+import { Interpreter } from '../interpreter/interpreter';
+import { Compiler } from '../compiler/compiler';
+import { analyzeFHIRPath } from '../analyzer/analyzer';
+import { RuntimeContextManager } from '../runtime/context';
+import { pprint } from '../parser/pprint';
+
+export class FHIRPathExpression implements IFHIRPathExpression {
+  constructor(
+    public readonly ast: ASTNode,
+    private readonly originalExpression: string
+  ) {}
+  
+  evaluate(input?: any, context?: EvaluationContext): any[] {
+    const interpreter = new Interpreter();
+    const inputArray = input === undefined ? [] : Array.isArray(input) ? input : [input];
+    const ctx = this.createContext(context, inputArray);
+    
+    const result = interpreter.evaluate(this.ast, inputArray, ctx);
+    
+    return result.value;
+  }
+  
+  compile(options?: CompileOptions): CompiledExpression {
+    const compiler = new Compiler();
+    const compiled = compiler.compile(this.ast);
+    
+    // Create the compiled function
+    const fn = (input?: any, context?: EvaluationContext): any[] => {
+      const inputArray = input === undefined ? [] : Array.isArray(input) ? input : [input];
+      const ctx = this.createContext(context, inputArray);
+      
+      return compiled.fn(ctx);
+    };
+    
+    // Add source property
+    Object.defineProperty(fn, 'source', {
+      value: options?.sourceMap ? this.originalExpression : this.toString(),
+      writable: false,
+      enumerable: true
+    });
+    
+    return fn as CompiledExpression;
+  }
+  
+  analyze(options?: AnalyzeOptions): AnalysisResult {
+    try {
+      // Create analyzer-compatible model provider
+      const analyzerModelProvider = options?.modelProvider ? {
+        resolveType: options.modelProvider.resolveType.bind(options.modelProvider),
+        getPropertyType: (type: any, propName: string) => {
+          const props = options.modelProvider!.getProperties(options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(type) : String(type));
+          const prop = props.find(p => p.name === propName);
+          if (!prop) return undefined;
+          return {
+            type: options.modelProvider!.resolveType(prop.type),
+            isSingleton: !prop.isCollection
+          };
+        },
+        isAssignable: (from: any, to: any) => {
+          const hierarchy = options.modelProvider!.getTypeHierarchy(options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(from) : String(from));
+          const toName = options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(to) : String(to);
+          return hierarchy.includes(toName);
+        },
+        getTypeName: (type: any) => String(type)
+      } : {
+        resolveType: () => undefined,
+        getPropertyType: () => undefined,
+        isAssignable: () => false,
+        getTypeName: () => 'unknown'
+      };
+      
+      const result = analyzeFHIRPath(this.ast, analyzerModelProvider);
+      
+      return {
+        type: result.resultType || { kind: 'unknown' },
+        isSingleton: result.resultIsSingleton || false,
+        errors: result.diagnostics.filter(d => d.severity === 'error').map(d => ({
+          message: d.message,
+          location: d.position ? {
+            line: d.position.line,
+            column: d.position.column,
+            offset: d.position.offset,
+            length: 1 // We don't have length info in Position
+          } : undefined,
+          code: 'ANALYSIS_ERROR'
+        })),
+        warnings: result.diagnostics.filter(d => d.severity === 'warning').map(d => ({
+          message: d.message,
+          location: d.position ? {
+            line: d.position.line,
+            column: d.position.column,
+            offset: d.position.offset,
+            length: 1
+          } : undefined,
+          code: 'ANALYSIS_WARNING'
+        }))
+      };
+    } catch (error) {
+      return {
+        type: { kind: 'unknown' },
+        isSingleton: false,
+        errors: [{
+          message: error instanceof Error ? error.message : String(error),
+          code: 'ANALYSIS_ERROR'
+        }],
+        warnings: []
+      };
+    }
+  }
+  
+  toString(): string {
+    return pprint(this.ast);
+  }
+  
+  private createContext(evalContext?: EvaluationContext, input: any[] = []) {
+    let ctx = RuntimeContextManager.create(input);
+    
+    if (evalContext?.variables) {
+      for (const [name, value] of Object.entries(evalContext.variables)) {
+        ctx = RuntimeContextManager.setVariable(ctx, name, Array.isArray(value) ? value : [value]);
+      }
+    }
+    
+    if (evalContext?.environment) {
+      // Environment variables are stored as regular variables with appropriate prefix
+      for (const [name, value] of Object.entries(evalContext.environment)) {
+        if (name.startsWith('$')) {
+          // Special environment variables
+          const varName = name.substring(1); // Remove $ prefix
+          ctx = RuntimeContextManager.setSpecialVariable(ctx, varName, Array.isArray(value) ? value : [value]);
+        } else {
+          // Regular environment variables
+          ctx = RuntimeContextManager.setVariable(ctx, name, Array.isArray(value) ? value : [value]);
+        }
+      }
+    }
+    
+    // Store custom functions in context for interpreter to access
+    if (evalContext?.customFunctions) {
+      // TODO: Custom functions need to be implemented through the registry
+      // For now, we'll store them in env
+      (ctx as any).customFunctions = evalContext.customFunctions;
+    }
+    
+    return ctx;
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,122 @@
+import type {
+  FHIRPathExpression,
+  CompiledExpression,
+  EvaluationContext,
+  CompileOptions,
+  AnalyzeOptions,
+  AnalysisResult,
+  InspectResult,
+  InspectOptions
+} from './types';
+import { FHIRPathParser } from '../parser/parser';
+import { 
+  type ParserOptions,
+  type ParseResult,
+  type ParseDiagnostic,
+  type TextRange
+} from '../parser/types';
+import type { ASTNode } from '../parser/ast';
+import { FHIRPathExpression as Expression } from './expression';
+import { FHIRPathError, parseError } from './errors';
+import { publicRegistry } from './registry';
+import { inspect as inspectImpl } from './inspect';
+
+// Export parser types for API consumers
+export { 
+  type ParserOptions,
+  type ParseResult,
+  type ParseDiagnostic,
+  type DiagnosticSeverity,
+  type TextRange,
+  type Position
+} from '../parser/types';
+
+// New parse function with mode support
+export function parse(expression: string, options: ParserOptions = {}): ParseResult {
+  const parser = new FHIRPathParser(expression, options);
+  return parser.parse();
+}
+
+// Convenience function for evaluation (throws on error)
+export function parseForEvaluation(expression: string): ASTNode {
+  try {
+    const result = parse(expression, { throwOnError: true });
+    return result.ast;
+  } catch (error) {
+    if (error instanceof Error) {
+      throw parseError(error.message, undefined, expression);
+    }
+    throw parseError(String(error), undefined, expression);
+  }
+}
+
+// Type guards for result types
+
+export function isStandardResult(result: ParseResult): result is ParseResult {
+  return 'ast' in result && 'diagnostics' in result && 'hasErrors' in result;
+}
+
+export function isDiagnosticResult(result: ParseResult): result is ParseResult & { isPartial: boolean; ranges: Map<ASTNode, TextRange> } {
+  return isStandardResult(result) && 'isPartial' in result && 'ranges' in result;
+}
+
+// Validate function - alternative to removed Validate mode
+export function validate(expression: string): { valid: boolean; diagnostics: ParseDiagnostic[] } {
+  const result = parse(expression);
+  if (isStandardResult(result)) {
+    return {
+      valid: !result.hasErrors,
+      diagnostics: result.diagnostics
+    };
+  }
+  // Should not happen, but handle gracefully
+  return { valid: true, diagnostics: [] };
+}
+
+
+// Evaluate expression directly
+export function evaluate(
+  expression: string | FHIRPathExpression,
+  input?: any,
+  context?: EvaluationContext
+): any[] {
+  const expr = typeof expression === 'string' 
+    ? new Expression(parseForEvaluation(expression), expression)
+    : expression;
+  return expr.evaluate(input, context);
+}
+
+// Compile to optimized function
+export function compile(
+  expression: string | FHIRPathExpression,
+  options?: CompileOptions
+): CompiledExpression {
+  const expr = typeof expression === 'string' 
+    ? new Expression(parseForEvaluation(expression), expression)
+    : expression;
+  return expr.compile(options);
+}
+
+// Analyze expression for validation
+export function analyze(
+  expression: string | FHIRPathExpression,
+  options?: AnalyzeOptions
+): AnalysisResult {
+  const expr = typeof expression === 'string' 
+    ? new Expression(parseForEvaluation(expression), expression)
+    : expression;
+  return expr.analyze(options);
+}
+
+// Inspect expression with debugging information
+export function inspect(
+  expression: string | FHIRPathExpression,
+  input?: any,
+  context?: EvaluationContext,
+  options?: InspectOptions
+): InspectResult {
+  return inspectImpl(expression, input, context, options);
+}
+
+// Default registry instance
+export const registry = publicRegistry;

package/src/api/inspect.ts

@@ -0,0 +1,99 @@
+import type { 
+  FHIRPathExpression,
+  EvaluationContext,
+  InspectResult,
+  InspectOptions,
+  ErrorInfo,
+  WarningInfo
+} from './types';
+import { parseForEvaluation } from './index';
+import { FHIRPathExpression as Expression } from './expression';
+import { Interpreter } from '../interpreter/interpreter';
+import { RuntimeContextManager } from '../runtime/context';
+import { createDebugContext, isDebugContext } from '../runtime/debug-context';
+import { FHIRPathError } from './errors';
+
+/**
+ * Inspect a FHIRPath expression, providing rich debugging information
+ * including traces, AST, execution time, and optionally step-by-step evaluation
+ */
+export function inspect(
+  expression: string | FHIRPathExpression,
+  input?: any,
+  context?: EvaluationContext,
+  options?: InspectOptions
+): InspectResult {
+  const startTime = performance.now();
+  
+  // Parse if string
+  const expr = typeof expression === 'string' 
+    ? new Expression(parseForEvaluation(expression), expression)
+    : expression;
+  const exprString = typeof expression === 'string' ? expression : expr.toString();
+  
+  // Prepare input (default to empty array)
+  const inputValue = input === undefined ? [] : Array.isArray(input) ? input : [input];
+  
+  // Create runtime context
+  const runtimeContext = RuntimeContextManager.create(inputValue, context?.variables);
+  
+  // Convert to debug context
+  const debugContext = createDebugContext(runtimeContext, options);
+  
+  // Initialize result
+  const errors: ErrorInfo[] = [];
+  const warnings: WarningInfo[] = [];
+  let result: any[] = [];
+  
+  try {
+    // Create interpreter
+    const interpreter = new Interpreter();
+    
+    // Evaluate with debug context
+    const evalResult = interpreter.evaluate(expr.ast, inputValue, debugContext);
+    result = evalResult.value;
+  } catch (error) {
+    // Capture error information
+    const errorInfo: ErrorInfo = {
+      message: error instanceof Error ? error.message : String(error),
+      type: error instanceof FHIRPathError ? error.name : 'Error'
+    };
+    
+    if (error instanceof Error && error.stack) {
+      errorInfo.stack = error.stack;
+    }
+    
+    errors.push(errorInfo);
+    
+    // Re-throw if it's a critical error
+    if (error instanceof FHIRPathError && error.name === 'ParseError') {
+      throw error;
+    }
+  }
+  
+  const executionTime = performance.now() - startTime;
+  
+  // Build result
+  const inspectResult: InspectResult = {
+    result,
+    expression: exprString,
+    ast: expr.ast,
+    executionTime,
+    traces: debugContext.traces
+  };
+  
+  // Add optional fields
+  if (debugContext.steps && debugContext.steps.length > 0) {
+    inspectResult.evaluationSteps = debugContext.steps;
+  }
+  
+  if (errors.length > 0) {
+    inspectResult.errors = errors;
+  }
+  
+  if (warnings.length > 0) {
+    inspectResult.warnings = warnings;
+  }
+  
+  return inspectResult;
+}

package/src/api/registry.ts

@@ -0,0 +1,128 @@
+import type { 
+  RegistryAPI, 
+  OperationMetadata, 
+  OperationInfo 
+} from './types';
+import { Registry } from '../registry/registry';
+import type { Operation } from '../registry/types';
+
+export class PublicRegistryAPI implements RegistryAPI {
+  listFunctions(): OperationMetadata[] {
+    return Registry.getAllFunctions().map(op => this.toMetadata(op));
+  }
+  
+  listOperators(): OperationMetadata[] {
+    const operators = [
+      ...Registry.getOperatorsByForm('infix'),
+      ...Registry.getOperatorsByForm('prefix'),
+      ...Registry.getOperatorsByForm('postfix')
+    ];
+    return operators.map(op => this.toMetadata(op));
+  }
+  
+  listAllOperations(): OperationMetadata[] {
+    return Registry.getAllOperations().map(op => this.toMetadata(op));
+  }
+  
+  hasOperation(name: string): boolean {
+    return Registry.get(name) !== undefined;
+  }
+  
+  hasFunction(name: string): boolean {
+    const op = Registry.get(name);
+    return op !== undefined && op.kind === 'function';
+  }
+  
+  hasOperator(symbol: string): boolean {
+    const op = Registry.get(symbol);
+    return op !== undefined && op.kind === 'operator';
+  }
+  
+  getOperationInfo(name: string): OperationInfo | undefined {
+    const op = Registry.get(name);
+    if (!op) return undefined;
+    
+    return this.toOperationInfo(op);
+  }
+  
+  canRegisterFunction(name: string): boolean {
+    // Check if name is valid and not already taken
+    if (!name || typeof name !== 'string') return false;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) return false;
+    
+    // Check if already exists as built-in
+    return !this.hasOperation(name);
+  }
+  
+  private toMetadata(op: Operation): OperationMetadata {
+    return {
+      name: op.name,
+      kind: op.kind,
+      syntax: {
+        notation: op.syntax.notation
+      }
+    };
+  }
+  
+  private toOperationInfo(op: Operation): OperationInfo {
+    const info: OperationInfo = {
+      ...this.toMetadata(op),
+      signature: {}
+    };
+    
+    // Add input signature for functions
+    if (op.kind === 'function' && op.signature.input) {
+      info.signature.input = {
+        types: this.extractTypes(op.signature.input.types),
+        cardinality: op.signature.input.cardinality
+      };
+    }
+    
+    // Add parameters
+    if ('parameters' in op.signature && op.signature.parameters && op.signature.parameters.length > 0) {
+      info.signature.parameters = op.signature.parameters.map((param: any) => ({
+        name: param.name,
+        types: this.extractTypes(param.types),
+        cardinality: param.cardinality,
+        optional: param.optional
+      }));
+    }
+    
+    // Add output signature
+    if (op.signature.output) {
+      info.signature.output = {
+        type: typeof op.signature.output.type === 'string' 
+          ? op.signature.output.type 
+          : 'dynamic',
+        cardinality: typeof op.signature.output.cardinality === 'string'
+          ? (op.signature.output.cardinality === 'all-singleton' ? 'singleton' : op.signature.output.cardinality as any)
+          : undefined
+      };
+    }
+    
+    // Add description if available (for now, operations don't have description in the type)
+    // TODO: Add description to Operation type if needed
+    
+    // Add examples if available (for now, operations don't have examples in the type)
+    // TODO: Add examples to Operation type if needed
+    
+    return info;
+  }
+  
+  private extractTypes(constraint?: any): string[] | undefined {
+    if (!constraint) return undefined;
+    
+    if (constraint.kind === 'primitive' || constraint.kind === 'class') {
+      return constraint.types;
+    } else if (constraint.kind === 'union' && constraint.types) {
+      return constraint.types;
+    } else if (constraint.kind === 'any') {
+      return ['any'];
+    }
+    
+    return undefined;
+  }
+}
+
+// Singleton instance
+export const publicRegistry = new PublicRegistryAPI();