fhirpath-ts 0.1.0 → 0.2.0

package/dist/analyzer/analyze.js

@@ -1,13 +1,25 @@
 import "../functions/install.js";
-import { BUILTIN_ENV_VARIABLE_NAMES } from "../engine/context.js";
+import { bareEnvironmentName, BUILTIN_ENV_VARIABLE_NAMES, normalizeEnvKeys } from "../engine/context.js";
 import { FhirPathSyntaxError } from "../errors.js";
 import { describeArity, functions } from "../functions/registry.js";
 import { parse } from "../parser/parser.js";
-import { unsatisfiedInput, valueKindOfTypeName } from "../values/type-compat.js";
+import { canonicalFocusType, commonValueKind, resolveByInput, resolveSystemTypeName, rootTypeMatches, SYSTEM_TYPE_LOCAL_NAMES, unsatisfiedInput, } from "../values/type-compat.js";
 import { FHIR_PRIMITIVE_TO_SYSTEM, typeLocalName } from "../values/typed-value.js";
+import { analyzerEnvironmentVariables, isRuntimeAnalyzerVariable, runtimeAnalyzerEnvironmentVariables, } from "./declarations.js";
+import { applyOperatorResultRule, applyTypeOperatorResultRule } from "./operator-rules.js";
 import { hasNestedUnboundedQuantifier } from "./regex-safety.js";
-import { FUNCTION_SIGNATURES, singleAnd, unionStates, withSingle, } from "./signatures.js";
+import { applyResultRule, FUNCTION_SIGNATURES, singleAnd, unionStates, withSingle, } from "./signatures.js";
 const UNKNOWN = { types: undefined, single: undefined };
+/** A runtime-analyzed function result no longer has exact facts about its input focus. */
+function callResult(state, runtime) {
+    return runtime
+        ? {
+            types: state.types,
+            single: state.single,
+            ...(state.targets !== undefined && { targets: state.targets }),
+        }
+        : state;
+}
 function emptyScope() {
     return { vars: new Map(), hasDynamic: false };
 }
@@ -77,7 +89,11 @@ export function analyzeExpressionDetailed(expression, options) {
             result: { types: undefined, single: undefined },
         };
     }
-    const analyzer = new Analyzer(options);
+    return analyzeAstDetailed(ast, options);
+}
+/** Analyze an already parsed expression, optionally with a runtime-derived input state. */
+function analyzeAstDetailed(ast, options, root) {
+    const analyzer = new Analyzer(options, root);
     const state = analyzer.walk(ast, analyzer.rootState(), emptyScope());
     return {
         diagnostics: analyzer.diagnostics,
@@ -85,30 +101,43 @@ export function analyzeExpressionDetailed(expression, options) {
         result: { types: state.types, single: state.single },
     };
 }
+/** Analyze a parsed expression using facts from the actual evaluation focus. */
+export function analyzeRuntimeAstDetailed(ast, options, root) {
+    return analyzeAstDetailed(ast, options, root);
+}
 class Analyzer {
     diagnostics = [];
     dependencies = new Set();
     model;
-    inputType;
+    root;
+    runtime;
     frames = [];
     /** Every declaration of each host-supplied name; one entry unless the name is overloaded. */
     customFunctions;
     declaredVariables;
-    constructor(options) {
+    activeExpressionFunctions = new Set();
+    constructor(options, root) {
         this.model = options?.model;
+        this.runtime = root !== undefined;
         const inputType = options?.inputType;
-        this.inputType = inputType === undefined ? undefined : (this.model?.resolveType(inputType) ?? inputType);
+        this.root =
+            root ??
+                (inputType === undefined
+                    ? { types: undefined, single: undefined }
+                    : { types: [this.model?.resolveType(inputType) ?? inputType], single: true });
         this.customFunctions = new Map(Object.entries(options?.functions ?? {}).map(([name, declared]) => [
             name,
-            ('overloads' in declared ? declared.overloads : [declared]).map(resolvedDeclaration),
-        ]));
-        this.declaredVariables = new Map(Object.entries(options?.variables ?? {}).map(([name, variable]) => [
-            name.startsWith('%') ? name.slice(1) : name,
-            variable,
+            ('overloads' in declared ? declared.overloads : [declared]).map(declaration => resolvedDeclaration(declaration, this.model, this.runtime)),
         ]));
+        this.declaredVariables = new Map(Object.entries(normalizeEnvKeys(options?.variables)));
     }
     rootState() {
-        return this.inputType === undefined ? UNKNOWN : { types: [this.inputType], single: true, rawInput: true };
+        return {
+            types: this.root.types,
+            single: this.root.single,
+            rawInput: true,
+            ...(this.root.exactTypes !== undefined && { exactTypes: this.root.exactTypes }),
+        };
     }
     walk(node, input, scope) {
         switch (node.kind) {
@@ -181,7 +210,7 @@ class Analyzer {
         }
         const declared = this.declaredVariables.get(node.name);
         if (declared !== undefined) {
-            return { types: declared.types?.map(type => this.canonicalize(type)), single: declared.single };
+            return this.declaredVariableState(declared);
         }
         switch (node.name) {
             case 'context':
@@ -228,26 +257,50 @@ class Analyzer {
         if (input.types !== undefined && input.types.length === 0) {
             return { types: [], single: true };
         }
+        const exactTypes = input.exactTypes?.filter(type => rootTypeMatches(this.model, type, node.name));
+        if (exactTypes !== undefined && exactTypes.length > 0) {
+            const types = input.types?.filter(type => rootTypeMatches(this.model, type, node.name));
+            return {
+                types: types === undefined ? undefined : [...new Set(types)],
+                single: input.single,
+                exactTypes,
+                ...(input.rawInput === true && { rawInput: true }),
+            };
+        }
         if (input.types === undefined) {
             // Even with an unknown input, a root identifier naming a model type anchors
             // the state — this is what checks `Patient.nope` without an inputType option.
-            const asType = this.model?.resolveType(node.name);
+            const asType = this.model?.resolveType(node.name) ?? resolveSystemTypeName(node.name);
             if (asType !== undefined) {
-                return { types: [asType], single: true };
+                return {
+                    types: [asType],
+                    single: true,
+                    ...(input.exactTypes !== undefined && {
+                        exactTypes: input.exactTypes.filter(type => this.model?.isSubtypeOf(type, asType) === true),
+                    }),
+                };
             }
             return UNKNOWN;
         }
         // Root rule: an identifier naming the (super)type of the context is the context.
-        if (this.model) {
-            const asType = this.model.resolveType(node.name);
-            if (asType !== undefined && input.types.some(type => this.model?.isSubtypeOf(type, asType))) {
+        {
+            const asType = this.model?.resolveType(node.name) ?? resolveSystemTypeName(node.name);
+            let matchingTypes = [];
+            if (asType !== undefined) {
+                matchingTypes = input.types.filter(type => rootTypeMatches(this.model, type, node.name));
+            }
+            if (asType !== undefined && matchingTypes.length > 0) {
                 // The runtime matches a type name against the raw input only through the
                 // resourceType discriminator (values/typed-value.ts), so a non-resource
                 // name never matches there and the whole path navigates to empty.
-                if (input.rawInput === true && !this.isResourceType(asType)) {
+                if (input.rawInput === true && !asType.startsWith('System.') && !this.isResourceType(asType)) {
                     this.report('datatype-root', `'${node.name}' is not a resource type, and a type-name root matches only a resource's resourceType, so this always evaluates to empty — navigate from the input with a relative path`, node.span);
                 }
-                return input;
+                return {
+                    ...input,
+                    types: matchingTypes,
+                    ...(input.exactTypes !== undefined && { exactTypes: input.exactTypes }),
+                };
             }
         }
         const found = [];
@@ -371,7 +424,8 @@ class Analyzer {
         const signature = registered !== undefined ? FUNCTION_SIGNATURES[node.name] : this.toSignature(custom?.signature);
         if (!signature) {
             this.walkUncheckedArguments(node, input, scope);
-            return UNKNOWN;
+            const expressionResult = this.expressionFunctionResult(node.name, custom, input, scope);
+            return expressionResult === undefined ? UNKNOWN : callResult(expressionResult, this.runtime);
         }
         this.checkCallInput(node, signature, input);
         const { argStates, typeTarget } = this.walkArguments(node, signature, input, scope);
@@ -384,7 +438,105 @@ class Analyzer {
         if ((node.name === 'ofType' || node.name === 'as') && typeTarget !== undefined) {
             return { types: this.narrowTypes(input, typeTarget, node.span), single: input.single };
         }
-        return signature.result(input, argStates);
+        const expressionResult = this.expressionFunctionResult(node.name, custom, input, scope);
+        if (expressionResult !== undefined) {
+            return callResult(expressionResult, this.runtime);
+        }
+        return callResult(applyResultRule(signature.result, input, argStates), this.runtime);
+    }
+    /** Apply the expression-body and criteria rules in one place for signed and unsigned declarations. */
+    expressionFunctionResult(name, declaration, input, scope) {
+        if (declaration?.expression === undefined) {
+            for (const possible of declaration?.possibleBodies ?? []) {
+                if (possible.expression !== undefined) {
+                    this.walkExpressionFunction(name, possible.expression, possible.variables, this.expressionBodyInput(possible, input), scope);
+                }
+            }
+            return undefined;
+        }
+        const expression = declaration.expression;
+        const bodyInput = this.expressionBodyInput(declaration, input);
+        if (declaration.criteria === true) {
+            this.walkExpressionFunction(name, expression, declaration.variables, bodyInput, scope);
+            return { types: ['System.Boolean'], single: true };
+        }
+        if (declaration.signature?.result === undefined) {
+            return this.walkExpressionFunction(name, expression, declaration.variables, bodyInput, scope);
+        }
+        if (this.runtime) {
+            this.walkExpressionFunction(name, expression, declaration.variables, bodyInput, scope);
+        }
+        return undefined;
+    }
+    /** A declared input type is the contract an expression body must satisfy. */
+    expressionBodyInput(declaration, callInput) {
+        const declared = declaration.signature?.input?.types;
+        if (declared === undefined) {
+            return callInput;
+        }
+        const types = declared
+            .map(type => this.model === undefined ? resolveSystemTypeName(typeLocalName(type)) : canonicalFocusType(this.model, type))
+            .filter((type) => type !== undefined);
+        if (types.length === 0) {
+            return callInput;
+        }
+        return {
+            types: [...new Set(types)],
+            single: callInput.single,
+            ...(callInput.targets !== undefined && { targets: callInput.targets }),
+        };
+    }
+    /** Infer a literal expression-function body under its call focus and temporary local environment declarations. */
+    walkExpressionFunction(name, expression, variables, input, callerScope) {
+        if (this.activeExpressionFunctions.has(name)) {
+            return UNKNOWN;
+        }
+        let ast = expression.ast;
+        if (ast === undefined) {
+            try {
+                ast = parse(expression.source);
+            }
+            catch {
+                return UNKNOWN;
+            }
+        }
+        const functionScope = forkScope(callerScope);
+        for (const [declaredName, variable] of Object.entries(variables ?? {})) {
+            const bare = bareEnvironmentName(declaredName);
+            // defineVariable() values have priority over environment overlays at runtime.
+            if (!functionScope.vars.has(bare)) {
+                functionScope.vars.set(bare, this.declaredVariableState(variable));
+            }
+        }
+        const diagnosticCount = this.diagnostics.length;
+        this.activeExpressionFunctions.add(name);
+        this.frames.push(input);
+        try {
+            return this.walk(ast, input, functionScope);
+        }
+        finally {
+            if (this.runtime) {
+                for (const diagnostic of this.diagnostics.slice(diagnosticCount)) {
+                    diagnostic.message = `Custom function '${name}': ${diagnostic.message}`;
+                }
+            }
+            else {
+                // Body spans index another source string, so callers cannot display these diagnostics correctly.
+                this.diagnostics.length = diagnosticCount;
+            }
+            this.frames.pop();
+            this.activeExpressionFunctions.delete(name);
+        }
+    }
+    /** Convert one declared environment value into the same state used for scoped variables. */
+    declaredVariableState(declared) {
+        const exactTypes = this.runtime && isRuntimeAnalyzerVariable(declared) ? declared.exactTypes : undefined;
+        return {
+            types: declared.types?.map(type => this.canonicalize(type)),
+            single: declared.single,
+            ...(declared.targets !== undefined && { targets: declared.targets.map(type => this.canonicalize(type)) }),
+            ...(exactTypes !== undefined && { exactTypes }),
+        };
     }
     /**
      * Selects a host declaration from the focus. One match keeps its full
@@ -396,9 +548,18 @@ class Analyzer {
         if (candidates === undefined || candidates.length <= 1) {
             return candidates?.[0];
         }
+        if (this.runtime && (input.exactTypes !== undefined || this.model === undefined)) {
+            const resolution = resolveByInput(this.model, candidates, candidate => candidate.signature?.input?.types, input.exactTypes ?? []);
+            return 'resolved' in resolution ? resolution.resolved : mergedDeclaration(candidates);
+        }
         const focus = input.types ?? [];
         const fitting = candidates.filter(candidate => unsatisfiedInput(this.model, candidate.signature?.input?.types, focus) === undefined);
-        return fitting.length === 1 ? fitting[0] : mergedDeclaration(fitting.length === 0 ? candidates : fitting);
+        if (fitting.length === 1) {
+            return fitting[0];
+        }
+        const possible = fitting.length === 0 ? candidates : fitting;
+        const merged = mergedDeclaration(possible);
+        return this.runtime ? { ...merged, possibleBodies: possible } : merged;
     }
     /** Without a signature the arguments still walk (for their own diagnostics), each in a scope fork. */
     walkUncheckedArguments(node, input, scope) {
@@ -535,7 +696,11 @@ class Analyzer {
         return {
             ...(declared.input !== undefined && { input: declared.input }),
             ...(declared.args !== undefined && { args: declared.args }),
-            result: () => ({ types, single }),
+            result: {
+                kind: 'fixed',
+                ...(types !== undefined && { types }),
+                ...(single !== undefined && { single }),
+            },
         };
     }
     /**
@@ -580,7 +745,7 @@ class Analyzer {
     /** Check a type name; returns its canonical form, or undefined when it was reported unknown. */
     checkTypeName(parts, span) {
         if (parts.length === 2 && parts[0] === 'System') {
-            if (!SYSTEM_TYPE_NAMES.has(parts[1])) {
+            if (!SYSTEM_TYPE_LOCAL_NAMES.has(parts[1])) {
                 this.report('unknown-type', `Unknown type 'System.${parts[1]}'`, span);
                 return undefined;
             }
@@ -592,11 +757,11 @@ class Analyzer {
             return undefined;
         }
         const resolved = this.model?.resolveType(name);
-        if (this.model && resolved === undefined && !SYSTEM_TYPE_NAMES.has(name)) {
+        if (this.model && resolved === undefined && !SYSTEM_TYPE_LOCAL_NAMES.has(name)) {
             this.report('unknown-type', `Unknown type '${parts.join('.')}'`, span);
             return undefined;
         }
-        return resolved ?? (SYSTEM_TYPE_NAMES.has(name) ? `System.${name}` : name);
+        return resolved ?? (SYSTEM_TYPE_LOCAL_NAMES.has(name) ? `System.${name}` : name);
     }
     walkBinary(node, input, scope) {
         // Operator operands are separate chains: each analyzes against its own scope
@@ -612,23 +777,14 @@ class Analyzer {
             case 'div':
             case 'mod': {
                 this.checkArithmetic(node.operator, left, right, node.span);
-                // Quantity arithmetic yields Quantity (4.0 'g' / 2.0 'm' is 2 'g/m');
-                // plain division yields Decimal; everything else keeps the operand type.
-                const quantity = (node.operator === '*' || node.operator === '/') &&
-                    (kindOf(left) === 'Quantity' || kindOf(right) === 'Quantity');
-                const types = quantity
-                    ? ['System.Quantity']
-                    : node.operator === '/'
-                        ? ['System.Decimal']
-                        : (left.types ?? right.types);
-                return { types, single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             }
             case '&':
                 this.requireSingle(left, node.left.span, "'&' expects single-item operands");
                 this.requireSingle(right, node.right.span, "'&' expects single-item operands");
                 this.requireKind(left, 'String', node.left.span, "'&' expects String operands");
                 this.requireKind(right, 'String', node.right.span, "'&' expects String operands");
-                return { types: ['System.String'], single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             case '<':
             case '>':
             case '<=':
@@ -636,13 +792,13 @@ class Analyzer {
                 this.requireSingle(left, node.left.span, `Operator '${node.operator}' expects single-item operands`);
                 this.requireSingle(right, node.right.span, `Operator '${node.operator}' expects single-item operands`);
                 this.checkComparable(left, right, node.span);
-                return { types: ['System.Boolean'], single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             case '=':
             case '!=':
             case '~':
             case '!~':
                 this.checkEquality(left, right, node.span);
-                return { types: ['System.Boolean'], single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             case 'and':
             case 'or':
             case 'xor':
@@ -651,24 +807,17 @@ class Analyzer {
                 // rule, so only cardinality is checkable here.
                 this.requireSingle(left, node.left.span, `'${node.operator}' expects single-item operands`);
                 this.requireSingle(right, node.right.span, `'${node.operator}' expects single-item operands`);
-                return { types: ['System.Boolean'], single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             }
             case '|': {
-                // A statically empty side contributes nothing: `{} | true` is one item.
-                if (left.types?.length === 0) {
-                    return right;
-                }
-                if (right.types?.length === 0) {
-                    return left;
-                }
-                return withSingle(unionStates([left, right]), false);
+                return applyOperatorResultRule(node.operator, left, right);
             }
             case 'in':
             case 'contains': {
                 const singletonSide = node.operator === 'in' ? left : right;
                 const singletonSpan = node.operator === 'in' ? node.left.span : node.right.span;
                 this.requireSingle(singletonSide, singletonSpan, `The ${node.operator === 'in' ? 'left' : 'right'} operand of '${node.operator}' must be a single item`);
-                return { types: ['System.Boolean'], single: true };
+                return applyOperatorResultRule(node.operator, left, right);
             }
             /* v8 ignore start -- the parser produces no other binary operators */
             default:
@@ -686,21 +835,16 @@ class Analyzer {
         const operand = this.walk(node.operand, input, scope);
         this.requireSingle(operand, node.operand.span, `'${node.operator}' expects a single item operand`);
         const resolved = this.checkTypeName(node.type.parts, node.type.span);
-        if (node.operator === 'is') {
-            return { types: ['System.Boolean'], single: true };
-        }
-        if (resolved === undefined) {
-            return UNKNOWN;
-        }
-        return { types: this.narrowTypes(operand, resolved, node.span), single: true };
+        const narrowed = node.operator === 'as' && resolved !== undefined ? this.narrowTypes(operand, resolved, node.span) : undefined;
+        return applyTypeOperatorResultRule(node.operator, narrowed);
     }
     checkArithmetic(operator, left, right, span) {
         if (isCollection(left) || isCollection(right)) {
             this.report('singleton-required', `Operator '${operator}' expects single-item operands${NARROW_HINT}`, span);
             return;
         }
-        const leftKind = kindOf(left);
-        const rightKind = kindOf(right);
+        const leftKind = commonValueKind(left.types);
+        const rightKind = commonValueKind(right.types);
         if (leftKind === undefined || rightKind === undefined || leftKind === 'Complex' || rightKind === 'Complex') {
             return;
         }
@@ -717,8 +861,8 @@ class Analyzer {
         }
     }
     checkComparable(left, right, span) {
-        const leftKind = kindOf(left);
-        const rightKind = kindOf(right);
+        const leftKind = commonValueKind(left.types);
+        const rightKind = commonValueKind(right.types);
         if (leftKind === undefined || rightKind === undefined) {
             return;
         }
@@ -727,8 +871,8 @@ class Analyzer {
         }
     }
     checkEquality(left, right, span) {
-        const leftKind = kindOf(left);
-        const rightKind = kindOf(right);
+        const leftKind = commonValueKind(left.types);
+        const rightKind = commonValueKind(right.types);
         if (leftKind === undefined || rightKind === undefined || leftKind === 'Complex' || rightKind === 'Complex') {
             return;
         }
@@ -737,7 +881,7 @@ class Analyzer {
         }
     }
     requireKind(state, kind, span, message) {
-        const actual = kindOf(state);
+        const actual = commonValueKind(state.types);
         if (actual === undefined) {
             return;
         }
@@ -752,31 +896,48 @@ class Analyzer {
 }
 /** Functions whose first argument is a regular expression pattern. */
 const REGEX_PATTERN_FUNCTIONS = new Set(['matches', 'matchesFull', 'replaceMatches']);
-const SYSTEM_TYPE_NAMES = new Set([
-    'Any',
-    'Boolean',
-    'String',
-    'Integer',
-    'Long',
-    'Decimal',
-    'Date',
-    'DateTime',
-    'Time',
-    'Quantity',
-]);
 /** Appended to singleton-misuse messages so the fix is spelled out, not just the rule. */
 const NARROW_HINT = ' — narrow it to one item with first(), last(), or single()';
 /** Statically known to possibly hold more than one item (types known, not a singleton). */
 function isCollection(state) {
     return state.types !== undefined && state.single === false;
 }
-function resolvedDeclaration(declared) {
+function resolvedDeclaration(declared, model, runtime) {
     if (declared.expression === undefined) {
-        return declared;
+        return {
+            ...(declared.minArity !== undefined && { minArity: declared.minArity }),
+            ...(declared.maxArity !== undefined && { maxArity: declared.maxArity }),
+            ...(declared.signature !== undefined && { signature: declared.signature }),
+        };
     }
     // An expression-defined function takes no arguments, which is how the runtime
     // calls it (`evaluateHostFunction`).
-    return { minArity: 0, maxArity: 0, ...(declared.signature !== undefined && { signature: declared.signature }) };
+    const expression = resolvedExpression(declared.expression);
+    return {
+        minArity: 0,
+        maxArity: 0,
+        ...(declared.signature !== undefined && { signature: declared.signature }),
+        ...(expression !== undefined && { expression }),
+        ...(declared.criteria !== undefined && { criteria: declared.criteria }),
+        ...((declared.env !== undefined || declared.envTypes !== undefined) && {
+            variables: runtime
+                ? runtimeAnalyzerEnvironmentVariables(declared.env, declared.envTypes, model)
+                : analyzerEnvironmentVariables(declared.env, declared.envTypes, model),
+        }),
+    };
+}
+function resolvedExpression(expression) {
+    if (typeof expression === 'string') {
+        return { source: expression };
+    }
+    const compiled = expression;
+    if (typeof compiled?.source !== 'string') {
+        return undefined;
+    }
+    return {
+        source: compiled.source,
+        ...(compiled.ast !== undefined && { ast: compiled.ast }),
+    };
 }
 /**
  * What several declarations of one name say together, for a call none of them
@@ -809,7 +970,7 @@ function mergedInput(candidates) {
 /** The union of the declarations' results, unknown as soon as one of them is. */
 function mergedResult(candidates) {
     const union = unionStates(candidates.map(candidate => ({
-        types: candidate.signature?.result?.types,
+        types: candidate.signature?.result?.types === undefined ? undefined : [...candidate.signature.result.types],
         single: candidate.signature?.result?.single,
     })));
     if (union.types === undefined && union.single === undefined) {
@@ -820,23 +981,6 @@ function mergedResult(candidates) {
         ...(union.single !== undefined && { single: union.single }),
     };
 }
-/** The behavior kind shared by every candidate type, or undefined when mixed/unknown. */
-function kindOf(state) {
-    if (state.types === undefined || state.types.length === 0) {
-        return undefined;
-    }
-    let kind;
-    for (const type of state.types) {
-        const typeKind = valueKindOfTypeName(type);
-        if (kind === undefined) {
-            kind = typeKind;
-        }
-        else if (kind !== typeKind) {
-            return undefined;
-        }
-    }
-    return kind;
-}
 function typeSpecifierParts(node) {
     if (node.kind === 'identifier') {
         return [node.name];