@atomic-ehr/fhirpath 0.0.1-canary.35b105d.20250724165800

package/src/analyzer/model-provider.ts

@@ -0,0 +1,244 @@
+import type { ModelProvider as IModelProvider, PropertyInfo, TypeRef } from './types';
+import type { FHIRSchema, SchemaRegistry, SchemaTypeRef } from './schemas/types';
+
+/**
+ * Model provider implementation using FHIR schemas
+ * Resolves types and properties through a schema registry
+ */
+export class ModelProvider implements IModelProvider {
+  private registry: SchemaRegistry;
+  private schemaListCache = new Map<string, FHIRSchema[]>();
+  
+  constructor(registry: SchemaRegistry) {
+    this.registry = registry;
+  }
+  
+  resolveType(typeName: string): TypeRef | undefined {
+    // Normalize type names - handle both "String" and "string" formats
+    const normalizedName = this.normalizeTypeName(typeName);
+    
+    const schemas = this.getSchemaList(normalizedName);
+    if (!schemas.length) return undefined;
+    
+    // Return opaque TypeRef (which is actually SchemaTypeRef)
+    const schemaTypeRef: SchemaTypeRef = {
+      schemas,
+      type: this.isPrimitiveType(normalizedName) ? normalizedName : 'complex-type'
+      // array is not set here - it's property-specific
+    };
+    return schemaTypeRef as unknown as TypeRef;
+  }
+  
+  getPropertyType(type: TypeRef, propertyName: string): PropertyInfo | undefined {
+    const schemaRef = type as unknown as SchemaTypeRef;
+    
+    // Search through type.schemas for the property
+    for (const schema of schemaRef.schemas) {
+      const element = schema.elements?.[propertyName];
+      if (element) {
+        // Handle union types
+        if (element.union === true && element.types) {
+          // For now, return Any type for unions
+          // In future, this could return a proper union type
+          return {
+            type: this.resolveType('Any')!,
+            isSingleton: !element.array
+          };
+        }
+        
+        // Build TypeRef for the property's type
+        let propSchemas: FHIRSchema[];
+        
+        if (element.elements) {
+          // Inline type with nested elements
+          const inlineSchema: FHIRSchema = {
+            name: `${this.getSchemaName(schema)}.${propertyName}`,
+            base: element.type || 'BackboneElement',
+            elements: element.elements
+          };
+          
+          // Get base type schemas if any
+          const baseSchemas = element.type ? this.getSchemaList(element.type) : [];
+          propSchemas = [inlineSchema, ...baseSchemas];
+        } else if (element.type) {
+          // Simple type reference
+          propSchemas = this.getSchemaList(element.type);
+        } else {
+          // No type specified - shouldn't happen in valid schemas
+          continue;
+        }
+        
+        const propTypeRef: SchemaTypeRef = {
+          schemas: propSchemas,
+          type: element.type && this.isPrimitiveType(element.type) ? element.type : 'complex-type',
+          array: element.array
+        };
+        
+        return {
+          type: propTypeRef as unknown as TypeRef,
+          isSingleton: !element.array
+        };
+      }
+    }
+    
+    return undefined;
+  }
+  
+  isAssignable(from: TypeRef, to: TypeRef): boolean {
+    const fromRef = from as unknown as SchemaTypeRef;
+    const toRef = to as unknown as SchemaTypeRef;
+    
+    // Same type is always assignable
+    if (fromRef.type === toRef.type && fromRef.type !== 'complex-type') {
+      return true;
+    }
+    
+    // Any is assignable to/from everything
+    if (fromRef.type === 'Any' || toRef.type === 'Any') {
+      return true;
+    }
+    
+    // For complex types, check if 'from' is a subtype of 'to'
+    if (fromRef.type === 'complex-type' && toRef.type === 'complex-type') {
+      const fromSchema = fromRef.schemas?.[0];
+      const toSchema = toRef.schemas?.[0];
+      
+      if (!fromSchema || !toSchema) return false;
+      
+      const fromName = this.getSchemaName(fromSchema);
+      const toName = this.getSchemaName(toSchema);
+      
+      // Check if 'to' appears in 'from's schema list (inheritance chain)
+      return fromRef.schemas.some(schema => this.getSchemaName(schema) === toName);
+    }
+    
+    // Handle primitive type inheritance (e.g., code extends string)
+    if (this.isPrimitiveType(fromRef.type) && this.isPrimitiveType(toRef.type)) {
+      const fromSchemas = this.getSchemaList(fromRef.type);
+      return fromSchemas.some(schema => schema.name === toRef.type);
+    }
+    
+    return false;
+  }
+  
+  getTypeName(type: TypeRef): string {
+    // Handle undefined type
+    if (!type || typeof type !== 'object') {
+      return 'Unknown';
+    }
+    
+    // Cast to our internal SchemaTypeRef structure
+    const typeRef = type as unknown as SchemaTypeRef;
+    
+    if (typeRef.type !== 'complex-type') {
+      // Capitalize primitive type names for display
+      return typeRef.type.charAt(0).toUpperCase() + typeRef.type.slice(1);
+    }
+    
+    // For complex types, use the name of the first schema
+    const schema = typeRef.schemas?.[0];
+    if (!schema) return 'Unknown';
+    return this.getSchemaName(schema);
+  }
+  
+  isCollectionType(type: TypeRef): boolean {
+    // The collection nature is carried in the TypeRef itself
+    const typeRef = type as unknown as SchemaTypeRef;
+    return typeRef.array || false;
+  }
+  
+  getCommonType(types: TypeRef[]): TypeRef | undefined {
+    if (types.length === 0) {
+      return undefined;
+    }
+    
+    if (types.length === 1) {
+      return types[0];
+    }
+    
+    // For simplicity, if all types are the same, return that type
+    const typeNames = types.map(t => this.getTypeName(t));
+    if (typeNames.every(name => name === typeNames[0])) {
+      return types[0];
+    }
+    
+    // Otherwise return Any
+    return this.resolveType('Any');
+  }
+  
+  private getSchemaList(typeName: string): FHIRSchema[] {
+    // Check cache first
+    if (this.schemaListCache.has(typeName)) {
+      return this.schemaListCache.get(typeName)!;
+    }
+    
+    // Build schema list by following base chain
+    const schemaList: FHIRSchema[] = [];
+    let currentType = typeName;
+    
+    while (currentType) {
+      const schema = this.registry.resolve(currentType);
+      if (!schema) break;
+      
+      // Add name to schema if not present (for primitives)
+      if (!schema.name) {
+        schema.name = currentType;
+      }
+      
+      schemaList.push(schema);
+      currentType = schema.base || '';
+    }
+    
+    // Cache the result
+    this.schemaListCache.set(typeName, schemaList);
+    return schemaList;
+  }
+  
+  private getSchemaName(schema: FHIRSchema): string {
+    // Schema should have a name, either explicit or set during resolution
+    return schema.name || 'Unknown';
+  }
+  
+  private isPrimitiveType(typeName: string): boolean {
+    // List of known primitive types
+    const primitives = [
+      'string', 'integer', 'decimal', 'boolean',
+      'date', 'dateTime', 'time', 'instant',
+      'code', 'id', 'uri', 'url', 'canonical',
+      'base64Binary', 'markdown', 'unsignedInt', 'positiveInt',
+      'Any'
+    ];
+    
+    return primitives.includes(typeName);
+  }
+  
+  private normalizeTypeName(typeName: string): string {
+    // Handle different naming conventions
+    // "String" -> "string", "Integer" -> "integer", etc.
+    
+    // First check if it's a primitive type with capital letter
+    const lowerName = typeName.toLowerCase();
+    if (this.isPrimitiveType(lowerName)) {
+      return lowerName;
+    }
+    
+    // Handle System namespace
+    if (typeName.startsWith('System.')) {
+      const baseName = typeName.substring(7);
+      const lowerBase = baseName.toLowerCase();
+      if (this.isPrimitiveType(lowerBase)) {
+        return lowerBase;
+      }
+      // System.Quantity -> Quantity
+      return baseName;
+    }
+    
+    // Handle FHIR namespace
+    if (typeName.startsWith('FHIR.')) {
+      return typeName.substring(5);
+    }
+    
+    // Default - return as is
+    return typeName;
+  }
+}

package/src/analyzer/schemas/index.ts

@@ -0,0 +1,2 @@
+// Export schema types and registry components
+export * from './types';

package/src/analyzer/schemas/types.ts

@@ -0,0 +1,40 @@
+// FHIR Schema type definitions
+// Note: Actual schema definitions are not included in the analyzer
+// In production, schemas should be loaded from the fhirschema library
+// Test schemas are located in test/test-schemas.ts
+
+export interface FHIRSchemaElement {
+  type?: string;              // Simple type reference
+  array?: boolean;            // Is this a collection?
+  union?: boolean | string;   // Union type indicator or discriminator
+  types?: string[];           // Union type options
+  elements?: Record<string, FHIRSchemaElement>; // Nested elements
+  valueset?: string;          // Terminology binding
+}
+
+export interface FHIRSchema {
+  name?: string;              // Schema name (for primitives and inline types)
+  base?: string;              // Parent type
+  primitive?: boolean;        // Is this a primitive type?
+  elements?: Record<string, FHIRSchemaElement>;
+}
+
+export interface SchemaRegistry {
+  resolve(typeName: string): FHIRSchema | undefined;
+}
+
+// Static implementation for testing
+export class StaticSchemaRegistry implements SchemaRegistry {
+  constructor(private schemas: Record<string, FHIRSchema>) {}
+  
+  resolve(typeName: string): FHIRSchema | undefined {
+    return this.schemas[typeName];
+  }
+}
+
+// Schema-based type reference used internally by ModelProvider
+export interface SchemaTypeRef {
+  schemas: FHIRSchema[];  // List of schemas in inheritance order
+  type: string;           // 'complex-type' for FHIR types, or primitive name
+  array?: boolean;        // Optional, indicates if this is an array type
+}

package/src/analyzer/types.ts

@@ -0,0 +1,142 @@
+/**
+ * Type system interfaces for FHIRPath type analysis
+ * 
+ * Uses opaque type references to allow flexible implementation
+ */
+
+// Opaque type reference - implementation details hidden from analyzer
+export type TypeRef = unknown;
+
+/**
+ * Information about a property on a type
+ */
+export interface PropertyInfo {
+  type: TypeRef;
+  isSingleton: boolean;
+}
+
+/**
+ * Model provider interface for type resolution and navigation
+ */
+export interface ModelProvider {
+  /**
+   * Resolve a type name to an opaque type reference
+   */
+  resolveType(typeName: string): TypeRef | undefined;
+  
+  /**
+   * Get property type from an opaque type reference
+   */
+  getPropertyType(type: TypeRef, propertyName: string): PropertyInfo | undefined;
+  
+  /**
+   * Check if one type is assignable to another
+   */
+  isAssignable(from: TypeRef, to: TypeRef): boolean;
+  
+  /**
+   * Get a human-readable name for a type (for error messages)
+   */
+  getTypeName(type: TypeRef): string;
+  
+  /**
+   * Check if a type is a collection type
+   */
+  isCollectionType?(type: TypeRef): boolean;
+  
+  /**
+   * Get common base type for union types
+   */
+  getCommonType?(types: TypeRef[]): TypeRef | undefined;
+}
+
+/**
+ * Parameter type information for functions
+ */
+export interface ParameterTypeInfo {
+  type?: TypeRef | 'expression' | 'any';
+  requiresSingleton?: boolean;
+  optional?: boolean;
+}
+
+/**
+ * Function type signature
+ */
+export interface FunctionTypeSignature {
+  // Input requirements
+  requiresSingleton: boolean;
+  propagateEmptyInput?: boolean;
+  requiresInputType?: string; // Required input type (e.g., 'string' for string functions)
+  
+  // Parameter type information
+  parameters?: ParameterTypeInfo[];
+  
+  // Return type calculation
+  returnType: (
+    inputType: TypeRef | undefined,
+    paramTypes: (TypeRef | undefined)[],
+    provider: ModelProvider
+  ) => TypeRef | undefined;
+  
+  // Return cardinality calculation
+  returnsSingleton: (
+    inputIsSingleton: boolean,
+    paramAreSingleton: boolean[]
+  ) => boolean;
+}
+
+/**
+ * Operator type signature
+ */
+export interface OperatorTypeSignature {
+  requiresLeftSingleton: boolean;
+  requiresRightSingleton: boolean;
+  
+  // For simple operators with fixed types
+  acceptedTypes?: Array<{
+    left: string;
+    right: string;
+    result: string;
+  }> | 'any';
+  
+  // For complex operators that need custom logic
+  returnType?: (
+    leftType: TypeRef | undefined,
+    rightType: TypeRef | undefined,
+    provider: ModelProvider
+  ) => TypeRef | undefined;
+  
+  returnsSingleton: boolean | ((left: boolean, right: boolean) => boolean);
+}
+
+/**
+ * Type analysis mode
+ */
+export enum AnalysisMode {
+  Strict = 'strict',   // Type mismatches are errors
+  Lenient = 'lenient' // Type mismatches are warnings, continue with Any
+}
+
+/**
+ * Type analysis result
+ */
+export interface TypeAnalysisResult {
+  // Annotated AST with type information
+  ast: import('../parser/ast').ASTNode;
+  
+  // Any errors or warnings encountered
+  diagnostics: TypeDiagnostic[];
+  
+  // Overall result type
+  resultType?: TypeRef;
+  resultIsSingleton?: boolean;
+}
+
+/**
+ * Type diagnostic (error or warning)
+ */
+export interface TypeDiagnostic {
+  severity: 'error' | 'warning';
+  message: string;
+  position?: import('../parser/ast').Position;
+}

package/src/api/builder.ts

@@ -0,0 +1,148 @@
+import type {
+  FHIRPathBuilder,
+  FHIRPathAPI,
+  ModelProvider,
+  CustomFunction,
+  FHIRPathExpression,
+  CompiledExpression,
+  AnalysisResult,
+  EvaluationContext,
+  CompileOptions,
+  AnalyzeOptions
+} from './types';
+import { parse, evaluate, compile, analyze } from './index';
+import { PublicRegistryAPI } from './registry';
+import { Registry } from '../registry/registry';
+import { invalidArgument } from './errors';
+
+export class FHIRPath {
+  static builder(): FHIRPathBuilder {
+    return new Builder();
+  }
+}
+
+class Builder implements FHIRPathBuilder {
+  private modelProvider?: ModelProvider;
+  private customFunctions: Map<string, CustomFunction> = new Map();
+  private variables: Map<string, any> = new Map();
+  
+  withModelProvider(provider: ModelProvider): this {
+    this.modelProvider = provider;
+    return this;
+  }
+  
+  withCustomFunction(name: string, fn: CustomFunction): this {
+    // Validate function name
+    if (!name || typeof name !== 'string') {
+      throw invalidArgument('Function name must be a non-empty string');
+    }
+    
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+      throw invalidArgument(`Invalid function name: ${name}. Must start with letter or underscore, followed by letters, numbers, or underscores`);
+    }
+    
+    // Check for conflicts with built-ins
+    if (Registry.get(name)) {
+      throw invalidArgument(`Cannot override built-in operation: ${name}`);
+    }
+    
+    this.customFunctions.set(name, fn);
+    return this;
+  }
+  
+  withVariable(name: string, value: any): this {
+    if (!name || typeof name !== 'string') {
+      throw invalidArgument('Variable name must be a non-empty string');
+    }
+    
+    this.variables.set(name, value);
+    return this;
+  }
+  
+  build(): FHIRPathAPI {
+    return new BuiltAPI(
+      this.modelProvider,
+      this.customFunctions,
+      this.variables
+    );
+  }
+}
+
+class BuiltAPI implements FHIRPathAPI {
+  public readonly registry: PublicRegistryAPI;
+  
+  constructor(
+    private readonly modelProvider: ModelProvider | undefined,
+    private readonly customFunctions: Map<string, CustomFunction>,
+    private readonly defaultVariables: Map<string, any>
+  ) {
+    // Create a registry wrapper that includes custom functions
+    this.registry = new BuiltRegistryAPI(this.customFunctions);
+  }
+  
+  parse(expression: string): FHIRPathExpression {
+    return parse(expression);
+  }
+  
+  evaluate(expression: string | FHIRPathExpression, input?: any): any[] {
+    const context = this.createContext();
+    return evaluate(expression, input, context);
+  }
+  
+  compile(expression: string | FHIRPathExpression, options?: CompileOptions): CompiledExpression {
+    // TODO: Integrate custom functions into compiled code
+    return compile(expression, options);
+  }
+  
+  analyze(expression: string | FHIRPathExpression, options?: AnalyzeOptions): AnalysisResult {
+    const mergedOptions: AnalyzeOptions = {
+      ...options,
+      modelProvider: options?.modelProvider || this.modelProvider
+    };
+    return analyze(expression, mergedOptions);
+  }
+  
+  private createContext(): EvaluationContext {
+    const context: EvaluationContext = {};
+    
+    if (this.modelProvider) {
+      context.modelProvider = this.modelProvider;
+    }
+    
+    if (this.defaultVariables.size > 0) {
+      context.variables = {};
+      for (const [name, value] of this.defaultVariables) {
+        context.variables[name] = value;
+      }
+    }
+    
+    if (this.customFunctions.size > 0) {
+      context.customFunctions = {};
+      for (const [name, fn] of this.customFunctions) {
+        context.customFunctions[name] = fn;
+      }
+    }
+    
+    return context;
+  }
+}
+
+// Extended registry that includes custom functions
+class BuiltRegistryAPI extends PublicRegistryAPI {
+  constructor(private customFunctions: Map<string, CustomFunction>) {
+    super();
+  }
+  
+  override hasFunction(name: string): boolean {
+    return super.hasFunction(name) || this.customFunctions.has(name);
+  }
+  
+  override hasOperation(name: string): boolean {
+    return super.hasOperation(name) || this.customFunctions.has(name);
+  }
+  
+  override canRegisterFunction(name: string): boolean {
+    // Can't register if it conflicts with built-ins or already registered custom
+    return super.canRegisterFunction(name) && !this.customFunctions.has(name);
+  }
+}

package/src/api/errors.ts

@@ -0,0 +1,134 @@
+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',
+  
+  // 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
+  );
+}