@atomic-ehr/fhirpath 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomic-ehr/fhirpath",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A TypeScript implementation of FHIRPath",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
   ],
   "scripts": {
     "build": "tsup",
-    "test": "bun test",
+    "test": "./scripts/test.sh",
+    "test:output": "bun test test/*",
     "typecheck": "bunx tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
@@ -42,12 +43,16 @@
     "@anthropic-ai/sdk": "^0.57.0",
     "@rgrove/parse-xml": "^4.2.0",
     "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
     "@types/jsdom": "^21.1.7",
+    "@types/lodash": "^4.17.20",
     "@types/node": "22.13.14",
     "@types/turndown": "^5.0.5",
     "antlr4ts": "^0.5.0-alpha.4",
     "antlr4ts-cli": "^0.5.0-alpha.4",
+    "js-yaml": "^4.1.0",
     "jsdom": "^26.1.0",
+    "lodash": "^4.17.21",
     "tsup": "8.5.0",
     "turndown": "^7.2.0",
     "typescript": "^5.8.3",
@@ -57,8 +62,8 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@atomic-ehr/fhir-canonical-manager": "latest",
-    "@atomic-ehr/fhirschema": "latest",
+    "@atomic-ehr/fhir-canonical-manager": "^0.0.11",
+    "@atomic-ehr/fhirschema": "^0.0.2",
     "@atomic-ehr/ucum": "^0.2.5"
   }
 }

package/src/analyzer/augmentor.ts

@@ -0,0 +1,242 @@
+import { NodeType } from '../types';
+import type { ASTNode, BinaryNode, UnaryNode, FunctionNode, IndexNode, CollectionNode, MembershipTestNode, TypeCastNode, TypeReferenceNode, QuantityNode } from '../types';
+import type { TriviaInfo } from '../types';
+import type { AnyCursorNode } from '../parser/cursor-nodes';
+import { isCursorNode, createCursorTypeNode } from '../parser/cursor-nodes';
+
+export interface AugmentationIndexes {
+  nodeById: Map<string, ASTNode>;
+  nodesByType: Map<NodeType | 'Error' | 'CursorNode', ASTNode[]>;
+  identifiers: Map<string, ASTNode[]>;
+}
+
+export interface AugmentationOptions {
+  input: string;
+  preserveTrivia?: boolean;
+  trivia?: {
+    leadingByStart?: Map<number, TriviaInfo[]>;
+    trailingByEnd?: Map<number, TriviaInfo[]>;
+  };
+  cursorPosition?: number;
+}
+
+export interface AugmentationResult {
+  ast: ASTNode;
+  indexes: AugmentationIndexes;
+}
+
+export function augment(ast: ASTNode, opts: AugmentationOptions): AugmentationResult {
+  const indexes: AugmentationIndexes = {
+    nodeById: new Map(),
+    nodesByType: new Map(),
+    identifiers: new Map(),
+  };
+  let nodeIdCounter = 0;
+
+  function enrich(node: ASTNode, parent?: ASTNode): void {
+    (node as any).id = `node_${nodeIdCounter++}`;
+    const start = node.range.start.offset ?? 0;
+    const end = node.range.end.offset ?? start;
+    (node as any).raw = opts.input.substring(start, end);
+    if (opts.preserveTrivia && opts.trivia) {
+      const s = node.range.start.offset ?? -1;
+      const e = node.range.end.offset ?? -1;
+      (node as any).leadingTrivia = opts.trivia.leadingByStart?.get(s) ?? [];
+      (node as any).trailingTrivia = opts.trivia.trailingByEnd?.get(e) ?? [];
+    }
+    if (parent) {
+      (node as any).parent = parent;
+    }
+    indexes.nodeById.set((node as any).id, node);
+    const bucket = indexes.nodesByType.get(node.type) || [];
+    bucket.push(node);
+    indexes.nodesByType.set(node.type, bucket);
+    if ((node as any).type === NodeType.Identifier) {
+      const name = (node as any).name as string;
+      const arr = indexes.identifiers.get(name) || [];
+      arr.push(node);
+      indexes.identifiers.set(name, arr);
+    }
+  }
+
+  function visit(node: ASTNode, parent?: ASTNode): void {
+    enrich(node, parent);
+    switch (node.type) {
+      case NodeType.Binary: {
+        const bin = node as BinaryNode;
+        (node as any).children = [bin.left, bin.right];
+        visit(bin.left, node);
+        visit(bin.right, node);
+        break;
+      }
+      case NodeType.Unary: {
+        const un = node as UnaryNode;
+        (node as any).children = [un.operand];
+        visit(un.operand, node);
+        break;
+      }
+      case NodeType.Function: {
+        const fn = node as FunctionNode;
+        (node as any).children = [fn.name, ...fn.arguments];
+        visit(fn.name, node);
+        for (const arg of fn.arguments) visit(arg, node);
+        break;
+      }
+      case NodeType.Index: {
+        const idx = node as IndexNode;
+        (node as any).children = [idx.expression, idx.index];
+        visit(idx.expression, node);
+        visit(idx.index, node);
+        break;
+      }
+      case NodeType.Collection: {
+        const coll = node as CollectionNode;
+        (node as any).children = [...coll.elements];
+        for (const el of coll.elements) visit(el, node);
+        break;
+      }
+      case NodeType.MembershipTest: {
+        const mt = node as MembershipTestNode;
+        (node as any).children = [mt.expression];
+        visit(mt.expression, node);
+        break;
+      }
+      case NodeType.TypeCast: {
+        const tc = node as TypeCastNode;
+        (node as any).children = [tc.expression];
+        visit(tc.expression, node);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  // First pass: enrich and index
+  visit(ast);
+
+  // Cursor-specific transform for ofType arguments
+  if (opts.cursorPosition !== undefined) {
+    const cursorPos = opts.cursorPosition;
+    function transform(node: ASTNode): ASTNode {
+      switch (node.type) {
+        case NodeType.Binary: {
+          const binary = node as BinaryNode;
+          if (binary.right.type === NodeType.Function) {
+            const func = binary.right as FunctionNode;
+      if ((func.name as any).name === 'ofType') {
+        func.arguments = func.arguments.map((arg) => {
+          if (isCursorNode(arg)) {
+            const cursorNode = arg as AnyCursorNode;
+            return createCursorTypeNode(cursorNode.position, 'ofType') as any;
+          }
+                if (arg.type === NodeType.Binary) {
+                  const binaryArg = arg as BinaryNode;
+                  if (isCursorNode(binaryArg.right)) {
+                    const cursorNode = binaryArg.right as AnyCursorNode;
+                    let partialText: string | undefined;
+                    if (binaryArg.left.type === NodeType.Identifier) {
+                      partialText = (binaryArg.left as any).name;
+                    }
+                    return createCursorTypeNode(cursorNode.position, 'ofType', partialText) as any;
+                  }
+                }
+                // New: identifier immediately before cursor inside ofType
+                if ((arg.type === NodeType.Identifier) && (arg as any).range?.end?.offset === cursorPos) {
+                  const name = (arg as any).name as string | undefined;
+                  return createCursorTypeNode(cursorPos, 'ofType', name) as any;
+                }
+                return arg;
+              });
+            }
+            binary.left = transform(binary.left);
+          } else {
+            binary.left = transform(binary.left);
+            binary.right = transform(binary.right);
+          }
+          break;
+        }
+        case NodeType.Function: {
+          const func = node as FunctionNode;
+          if ((func.name as any).name === 'ofType') {
+            func.arguments = func.arguments.map((arg) => {
+              if (isCursorNode(arg)) {
+                const cursorNode = arg as AnyCursorNode;
+                return createCursorTypeNode(cursorNode.position, 'ofType') as any;
+              }
+              if (arg.type === NodeType.Binary) {
+                const binaryArg = arg as BinaryNode;
+                if (isCursorNode(binaryArg.right)) {
+                  const cursorNode = binaryArg.right as AnyCursorNode;
+                  let partialText: string | undefined;
+                  if (binaryArg.left.type === NodeType.Identifier) {
+                    partialText = (binaryArg.left as any).name;
+                  }
+                  return createCursorTypeNode(cursorNode.position, 'ofType', partialText) as any;
+                }
+              }
+              // New: identifier immediately before cursor inside ofType
+              if ((arg.type === NodeType.Identifier) && (arg as any).range?.end?.offset === cursorPos) {
+                const name = (arg as any).name as string | undefined;
+                return createCursorTypeNode(cursorPos, 'ofType', name) as any;
+              }
+          return arg;
+        });
+        // If we still have a cursor type node without partial text, try to infer from source between '(' and cursor
+        if (func.arguments.length >= 1) {
+          const firstArg = func.arguments[0] as any;
+          if (isCursorNode(firstArg) && (firstArg as any).context === 'type' && (firstArg as any).partialText == null) {
+            const nameEnd = (func.name as any).range?.end?.offset ?? -1;
+            const start = nameEnd + 1; // after '('
+            const end = (firstArg as any).position ?? start;
+            if (start >= 0 && end >= start) {
+              const slice = opts.input.slice(start, end).trim();
+              const m = slice.match(/[A-Za-z][A-Za-z0-9.]*$/);
+              const inferred = m ? m[0] : undefined;
+              if (inferred && inferred.length > 0) {
+                func.arguments[0] = createCursorTypeNode(end, 'ofType', inferred) as any;
+              }
+            }
+          }
+        }
+      } else {
+            func.arguments = func.arguments.map(arg => transform(arg));
+          }
+          break;
+        }
+        case NodeType.Unary: {
+          const unary = node as UnaryNode;
+          unary.operand = transform(unary.operand);
+          break;
+        }
+        case NodeType.Index: {
+          const idx = node as IndexNode;
+          idx.expression = transform(idx.expression);
+          idx.index = transform(idx.index);
+          break;
+        }
+        case NodeType.Collection: {
+          const coll = node as CollectionNode;
+          coll.elements = coll.elements.map(el => transform(el));
+          break;
+        }
+        case NodeType.MembershipTest: {
+          const mt = node as MembershipTestNode;
+          mt.expression = transform(mt.expression);
+          break;
+        }
+        case NodeType.TypeCast: {
+          const tc = node as TypeCastNode;
+          tc.expression = transform(tc.expression);
+          break;
+        }
+      }
+      return node;
+    }
+    transform(ast);
+  }
+
+  return { ast, indexes };
+}
+
+// (legacy transform function removed; handled inline above)

package/src/analyzer/cursor-services.ts

@@ -0,0 +1,75 @@
+import { TokenType } from '../lexer';
+import { NodeType } from '../types';
+import type { ASTNode, IdentifierNode, BinaryNode, UnaryNode, FunctionNode, IndexNode, MembershipTestNode, TypeCastNode } from '../types';
+
+export function findNodeAtPosition(root: ASTNode, offset: number): ASTNode | null {
+  if (offset < root.range.start.offset! || offset > root.range.end.offset!) {
+    return null;
+  }
+  if ('children' in root && Array.isArray((root as any).children)) {
+    for (const child of (root as any).children as ASTNode[]) {
+      const found = findNodeAtPosition(child, offset);
+      if (found) return found;
+    }
+  }
+  switch (root.type) {
+    case NodeType.Binary: {
+      const bin = root as BinaryNode;
+      return findNodeAtPosition(bin.left, offset) || findNodeAtPosition(bin.right, offset) || root;
+    }
+    case NodeType.Unary: {
+      const un = root as UnaryNode;
+      return findNodeAtPosition(un.operand, offset) || root;
+    }
+    case NodeType.Function: {
+      const fn = root as FunctionNode;
+      const nameRes = findNodeAtPosition(fn.name, offset);
+      if (nameRes) return nameRes;
+      for (const arg of fn.arguments) {
+        const argRes = findNodeAtPosition(arg, offset);
+        if (argRes) return argRes;
+      }
+      return root;
+    }
+    default:
+      return root;
+  }
+}
+
+export function getExpectedTokens(node: ASTNode | null): TokenType[] {
+  if (!node) return getExpectedTokensForError();
+  switch (node.type) {
+    case NodeType.Binary:
+      return [TokenType.DOT, TokenType.LBRACKET];
+    case NodeType.Identifier:
+      return [TokenType.DOT, TokenType.LPAREN, TokenType.LBRACKET];
+    default:
+      return getExpectedTokensForError();
+  }
+}
+
+export function getExpectedTokensForError(): TokenType[] {
+  return [
+    TokenType.EOF,
+    TokenType.DOT,
+    TokenType.LBRACKET,
+    TokenType.LPAREN,
+    TokenType.OPERATOR,
+    TokenType.IDENTIFIER,
+  ];
+}
+
+export function getCompletions(node: ASTNode | null, identifiers?: Map<string, ASTNode[]>): string[] {
+  if (!node) return [];
+  const completions: string[] = [];
+  if (identifiers) {
+    for (const name of Array.from(identifiers.keys())) {
+      completions.push(name);
+    }
+  }
+  completions.push(
+    'where', 'select', 'first', 'last', 'tail',
+    'skip', 'take', 'count', 'empty', 'exists'
+  );
+  return completions;
+}

package/src/analyzer/scope-manager.ts

@@ -0,0 +1,57 @@
+import type { TypeInfo } from '../types';
+
+/**
+ * Manages lexical scopes for variables within the FHIRPath Analyzer.
+ * Provides a stack-based mechanism to enter and leave scopes,
+ * ensuring correct variable resolution based on their definition context.
+ */
+export class ScopeManager<T = TypeInfo> {
+  // Each element in the array represents a scope. The last element is the current scope.
+  // Each scope is a Map from variable name (e.g., '$this', '$index') to its TypeInfo.
+  private scopes: Map<string, T>[] = [new Map()];
+
+  /**
+   * Enters a new, empty scope.
+   * Variables defined after entering this scope will be local to it.
+   */
+  enterScope(): void {
+    this.scopes.push(new Map());
+  }
+
+  /**
+   * Leaves the current scope.
+   * If there's only one scope left (the global scope), it cannot be left.
+   */
+  leaveScope(): void {
+    if (this.scopes.length > 1) {
+      this.scopes.pop();
+    }
+  }
+
+  /**
+   * Sets a variable's type in the current scope.
+   * @param name The name of the variable (e.g., '$this').
+   * @param type The TypeInfo of the variable.
+   */
+  set(name: string, type: T): void {
+    if (this.scopes.length > 0) {
+      (this.scopes[this.scopes.length - 1] as Map<string, T>).set(name, type);
+    }
+  }
+
+  /**
+   * Retrieves a variable's type, searching from the current scope upwards through parent scopes.
+   * @param name The name of the variable.
+   * @returns The TypeInfo of the variable, or undefined if not found in any active scope.
+   */
+  get(name: string): T | undefined {
+    // Search from the innermost (current) scope outwards to the global scope
+    for (let i = this.scopes.length - 1; i >= 0; i--) {
+      const currentScope = this.scopes[i];
+      if (currentScope && currentScope.has(name)) {
+        return currentScope.get(name) as T;
+      }
+    }
+    return undefined;
+  }
+}

package/src/analyzer/trivia-indexer.ts

@@ -0,0 +1,58 @@
+import { Channel, TokenType } from '../lexer';
+import type { Token } from '../lexer';
+import type { TriviaInfo } from '../types';
+
+export interface TriviaSpans {
+  leadingByStart: Map<number, TriviaInfo[]>;
+  trailingByEnd: Map<number, TriviaInfo[]>;
+  tokenByStart: Map<number, Token>;
+  tokenByEnd: Map<number, Token>;
+}
+
+export function computeTriviaSpans(allTokens: Token[]): TriviaSpans {
+  const leadingByStart = new Map<number, TriviaInfo[]>();
+  const trailingByEnd = new Map<number, TriviaInfo[]>();
+  const tokenByStart = new Map<number, Token>();
+  const tokenByEnd = new Map<number, Token>();
+
+  let acc: TriviaInfo[] = [];
+  let lastDefault: Token | undefined;
+
+  const toTrivia = (token: Token): TriviaInfo | null => {
+    const range = token.range || {
+      start: { line: 0, character: 0, offset: token.start },
+      end: { line: 0, character: 0, offset: token.end }
+    };
+    if (token.type === TokenType.WHITESPACE) {
+      return { type: 'whitespace', value: token.value, range };
+    }
+    if (token.type === TokenType.LINE_COMMENT) {
+      return { type: 'lineComment', value: token.value, range };
+    }
+    if (token.type === TokenType.BLOCK_COMMENT) {
+      return { type: 'comment', value: token.value, range };
+    }
+    return null;
+  };
+
+  for (const tok of allTokens) {
+    const isHidden = tok.channel === Channel.HIDDEN;
+    if (isHidden) {
+      const trivia = toTrivia(tok);
+      if (trivia) acc.push(trivia);
+      continue;
+    }
+    const accCopy = acc.length ? acc.slice() : [];
+    if (lastDefault) {
+      trailingByEnd.set(lastDefault.end, accCopy);
+    }
+    leadingByStart.set(tok.start, accCopy);
+    tokenByStart.set(tok.start, tok);
+    tokenByEnd.set(tok.end, tok);
+    acc = [];
+    lastDefault = tok;
+  }
+
+  return { leadingByStart, trailingByEnd, tokenByStart, tokenByEnd };
+}
+

package/src/analyzer/type-compat.ts

@@ -0,0 +1,157 @@
+import type {
+  TypeInfo,
+  OperatorDefinition,
+  OperatorSignature,
+  FunctionDefinition,
+  FunctionSignature,
+  TypeName,
+} from '../types';
+import { registry } from '../registry';
+
+export function isTypeCompatible(source: TypeInfo, target: TypeInfo): boolean {
+  return registry.isTypeCompatible(source, target);
+}
+
+export function matchOperatorSignature(
+  left: TypeInfo,
+  right: TypeInfo,
+  def?: OperatorDefinition
+): OperatorSignature | undefined {
+  if (!def || !def.signatures || def.signatures.length === 0) return undefined;
+
+  let best: { sig: OperatorSignature; score: number; tieBias: number } | undefined;
+
+  for (const sig of def.signatures) {
+    const leftOk = isTypeCompatible(left, sig.left);
+    const rightOk = isTypeCompatible(right, sig.right);
+    if (!leftOk || !rightOk) continue;
+
+    const leftScore = specificity(left, sig.left);
+    const rightScore = specificity(right, sig.right);
+    let score = leftScore + rightScore;
+
+    // Prefer decimal math when any operand is Decimal
+    const anyActualDecimal = left.type === 'Decimal' || right.type === 'Decimal';
+    const sigHasDecimal = sig.left.type === 'Decimal' || sig.right.type === 'Decimal';
+    const tieBias = anyActualDecimal && sigHasDecimal ? 1 : 0;
+
+    if (!best || score > best.score || (score === best.score && tieBias > best.tieBias)) {
+      best = { sig, score, tieBias };
+    }
+  }
+
+  return best?.sig;
+}
+
+function specificity(actual: TypeInfo, required: TypeInfo): number {
+  if (required.type === 'Any') return 0;
+  if (actual.type === required.type) return 3;
+  // numeric widening
+  const numeric = new Set<TypeName>(['Integer', 'Decimal']);
+  if (numeric.has(actual.type) && numeric.has(required.type)) return 2;
+  return 1;
+}
+
+export function matchFunctionSignature(
+  input: TypeInfo,
+  args: TypeInfo[],
+  def?: FunctionDefinition
+): FunctionSignature | undefined {
+  if (!def || !def.signatures || def.signatures.length === 0) return undefined;
+
+  let best: { sig: FunctionSignature; score: number; tieBias: number } | undefined;
+
+  for (const sig of def.signatures) {
+    // Input compatibility (if specified)
+    if (sig.input && !isFunctionTypeCompatible(input, sig.input)) {
+      continue;
+    }
+
+    let ok = true;
+    let score = 0;
+    let tieBias = 0;
+    const params = sig.parameters || [];
+    for (let i = 0; i < Math.min(args.length, params.length); i++) {
+      const argType = args[i]!;
+      const param = params[i]!;
+      if (param.expression) {
+        continue; // expression params are analyzed in their own context
+      }
+
+      const isEmptyArg = argType.isEmpty || (argType.type === 'Any' && !argType.singleton);
+      if (isEmptyArg && !def.doesNotPropagateEmpty) {
+        continue; // empty propagates; don't penalize
+      }
+
+      if (!isFunctionTypeCompatible(argType, param.type)) {
+        ok = false;
+        break;
+      }
+      score += specificity(argType, param.type);
+
+      // Prefer decimal params when actual is Decimal
+      if (argType.type === 'Decimal' && param.type.type === 'Decimal') {
+        tieBias += 1;
+      }
+    }
+
+    if (!ok) continue;
+
+    // Add input specificity
+    if (sig.input) {
+      score += specificity(input, sig.input);
+      if (input.type === 'Decimal' && sig.input.type === 'Decimal') tieBias += 1;
+    }
+
+    if (!best || score > best.score || (score === best.score && tieBias > best.tieBias)) {
+      best = { sig, score, tieBias };
+    }
+  }
+
+  return best?.sig;
+}
+
+function isFunctionTypeCompatible(actual: TypeInfo, expected: TypeInfo): boolean {
+  // Enforce singleton when required
+  if (expected.singleton && !actual.singleton) return false;
+  if (expected.type === 'Any') return true;
+  if (actual.type === expected.type) return true;
+  // Allow Integer to be used where Decimal is expected (promotion)
+  if (expected.type === 'Decimal' && actual.type === 'Integer') return true;
+  return false;
+}
+
+export type ResultSpec =
+  | TypeInfo
+  | 'inputType'
+  | 'inputTypeSingleton'
+  | 'leftType'
+  | 'rightType'
+  | 'parameterType';
+
+export function resolveResultType(
+  spec: ResultSpec,
+  ctx: {
+    input?: TypeInfo;
+    left?: TypeInfo;
+    right?: TypeInfo;
+    firstParam?: TypeInfo;
+  }
+): TypeInfo {
+  if (typeof spec !== 'string') return spec;
+
+  switch (spec) {
+    case 'inputType':
+      return ctx.input || { type: 'Any', singleton: false };
+    case 'inputTypeSingleton':
+      return ctx.input ? { ...ctx.input, singleton: true } : { type: 'Any', singleton: true };
+    case 'leftType':
+      return ctx.left ? { ...ctx.left, singleton: false } : { type: 'Any', singleton: false };
+    case 'rightType':
+      return ctx.right ? { ...ctx.right, singleton: false } : { type: 'Any', singleton: false };
+    case 'parameterType':
+      return ctx.firstParam ? { ...ctx.firstParam, singleton: false } : { type: 'Any', singleton: false };
+    default:
+      return { type: 'Any', singleton: false };
+  }
+}