fhirpath-ts 0.0.0-bootstrap.0

package/dist/analyzer/analyze.js

@@ -0,0 +1,925 @@
+import "../functions/install.js";
+import { BUILTIN_ENV_VARIABLE_NAMES } 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 { FHIR_PRIMITIVE_TO_SYSTEM, typeLocalName } from "../values/typed-value.js";
+import { hasNestedUnboundedQuantifier } from "./regex-safety.js";
+import { FUNCTION_SIGNATURES, singleAnd, unionStates, withSingle, } from "./signatures.js";
+const UNKNOWN = { types: undefined, single: undefined };
+function emptyScope() {
+    return { vars: new Map(), hasDynamic: false };
+}
+function forkScope(scope) {
+    return { vars: new Map(scope.vars), hasDynamic: scope.hasDynamic };
+}
+/**
+ * Statically check one expression against the model: spec §11's strict-mode rules
+ * (singleton misuse, wrong operand and argument types, incomparable equality)
+ * plus unknown elements, functions, arities, type names, and variables.
+ * See: https://hl7.org/fhirpath/en/index.html#type-safety-and-strict-evaluation
+ */
+export function analyzeExpression(expression, options) {
+    return analyzeExpressionDetailed(expression, options).diagnostics;
+}
+/**
+ * Analyzes one source site with only facts visible in that file. A declared root
+ * does not prove which variables the later call provides. DTO sites may also
+ * receive variables and functions from base classes, other modules, or
+ * `project()`. Such sites omit unknown-variable diagnostics and report an
+ * unknown function only when it resembles a local column. A DTO without a known
+ * root receives syntax checks only. Use `analyzeDto` when the class and engine
+ * are loaded.
+ */
+export function analyzeSite(site, options) {
+    const declared = { ...site.functions, ...options?.functions };
+    const merged = {
+        ...options,
+        ...(site.inputType !== undefined && { inputType: site.inputType }),
+        ...(Object.keys(declared).length > 0 && { functions: declared }),
+    };
+    const diagnostics = analyzeExpression(site.expression, merged);
+    if (site.dto !== true) {
+        return site.inputType === undefined
+            ? diagnostics
+            : diagnostics.filter(diagnostic => diagnostic.code !== 'unknown-variable');
+    }
+    if (site.inputType === undefined) {
+        return diagnostics.filter(diagnostic => diagnostic.code === 'syntax');
+    }
+    const columns = Object.keys(site.functions ?? {});
+    return diagnostics.filter(diagnostic => {
+        if (diagnostic.code === 'unknown-variable') {
+            return false;
+        }
+        if (diagnostic.code !== 'unknown-function') {
+            return true;
+        }
+        return diagnostic.name !== undefined && nearestName(diagnostic.name, columns) !== undefined;
+    });
+}
+/** `analyzeExpression` plus the element paths the expression touches and its inferred result type. */
+export function analyzeExpressionDetailed(expression, options) {
+    let ast;
+    try {
+        ast = parse(expression);
+    }
+    catch (error) {
+        /* v8 ignore start -- parse only throws syntax errors */
+        if (!(error instanceof FhirPathSyntaxError)) {
+            throw error;
+        }
+        /* v8 ignore stop */
+        return {
+            diagnostics: [{ severity: 'error', code: 'syntax', message: error.message, span: error.span }],
+            elementDependencies: [],
+            result: { types: undefined, single: undefined },
+        };
+    }
+    const analyzer = new Analyzer(options);
+    const state = analyzer.walk(ast, analyzer.rootState(), emptyScope());
+    return {
+        diagnostics: analyzer.diagnostics,
+        elementDependencies: [...analyzer.dependencies],
+        result: { types: state.types, single: state.single },
+    };
+}
+class Analyzer {
+    diagnostics = [];
+    dependencies = new Set();
+    model;
+    inputType;
+    frames = [];
+    /** Every declaration of each host-supplied name; one entry unless the name is overloaded. */
+    customFunctions;
+    declaredVariables;
+    constructor(options) {
+        this.model = options?.model;
+        const inputType = options?.inputType;
+        this.inputType = inputType === undefined ? undefined : (this.model?.resolveType(inputType) ?? inputType);
+        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,
+        ]));
+    }
+    rootState() {
+        return this.inputType === undefined ? UNKNOWN : { types: [this.inputType], single: true, rawInput: true };
+    }
+    walk(node, input, scope) {
+        switch (node.kind) {
+            case 'null':
+                // The empty literal `{}` is statically at most one item, so it satisfies
+                // singleton operands (`{} + 1`, `{} and true` are spec-legal).
+                return { types: [], single: true };
+            case 'boolean':
+                return { types: ['System.Boolean'], single: true };
+            case 'string':
+                return { types: ['System.String'], single: true };
+            case 'number':
+                return {
+                    types: [node.isLong ? 'System.Long' : node.isDecimal ? 'System.Decimal' : 'System.Integer'],
+                    single: true,
+                };
+            case 'date':
+                return { types: ['System.Date'], single: true };
+            case 'dateTime':
+                return { types: ['System.DateTime'], single: true };
+            case 'time':
+                return { types: ['System.Time'], single: true };
+            case 'quantity':
+                return { types: ['System.Quantity'], single: true };
+            case 'external':
+                return this.walkExternal(node, scope);
+            case 'special':
+                return this.walkSpecial(node.name);
+            case 'identifier':
+                return this.walkIdentifier(node, input);
+            case 'dot':
+                // One scope threads the whole chain, so defineVariable() in an earlier
+                // link is visible to later links — exactly like the runtime.
+                return this.walk(node.right, this.walk(node.left, input, scope), scope);
+            case 'indexer': {
+                const target = this.walk(node.target, input, scope);
+                const index = this.walk(node.index, input, scope);
+                this.requireKind(index, 'Numeric', node.index.span, 'the indexer expects a single Integer');
+                return withSingle(target, true);
+            }
+            case 'call':
+                return this.walkCall(node, input, scope);
+            case 'unary': {
+                const operand = this.walk(node.operand, input, scope);
+                this.requireKind(operand, 'Numeric', node.operand.span, `unary '${node.operator}' expects a single number`);
+                return operand;
+            }
+            case 'binary':
+                return this.walkBinary(node, input, scope);
+            case 'typeOp':
+                return this.walkTypeOp(node, input, scope);
+            /* v8 ignore start -- exhaustive fallback */
+            default: {
+                const unreachable = node;
+                throw new Error(`Unhandled node ${String(unreachable)}`);
+            }
+            /* v8 ignore stop */
+        }
+    }
+    /**
+     * `%name`: defineVariable() bindings and built-in variables resolve with their
+     * known state; anything else is an undefined variable (spec §9), the same
+     * check the runtime applies. Host-supplied variables must be declared to the
+     * analyzer (AnalyzeOptions is the place this will grow).
+     */
+    walkExternal(node, scope) {
+        const defined = scope.vars.get(node.name);
+        if (defined !== undefined) {
+            return defined;
+        }
+        const declared = this.declaredVariables.get(node.name);
+        if (declared !== undefined) {
+            return { types: declared.types?.map(type => this.canonicalize(type)), single: declared.single };
+        }
+        switch (node.name) {
+            case 'context':
+            case 'resource':
+            case 'rootResource':
+                // Contained-resource re-rooting is a later refinement, mirroring the runtime.
+                return this.rootState();
+            case 'ucum':
+            case 'sct':
+            case 'loinc':
+                return { types: ['System.String'], single: true };
+            default:
+                break;
+        }
+        // FHIR-defined families expand to HL7 urls: %`vs-[name]`, %`ext-[name]`.
+        if (node.name.startsWith('vs-') || node.name.startsWith('ext-')) {
+            return { types: ['System.String'], single: true };
+        }
+        // A dynamically-named defineVariable() earlier in the chain may have bound
+        // this name, so reporting it as undefined could be wrong — stay quiet.
+        if (!scope.hasDynamic) {
+            this.report('unknown-variable', `Undefined environment variable %${node.name}`, node.span, 'error', node.name);
+        }
+        return UNKNOWN;
+    }
+    walkSpecial(name) {
+        if (name === 'this') {
+            return this.frames.at(-1) ?? this.rootState();
+        }
+        return name === 'index' ? { types: ['System.Integer'], single: true } : UNKNOWN;
+    }
+    /**
+     * A quantity's components (spec §4: `value` and `unit`), the one System type
+     * with navigable elements. The runtime reads them off the quantity's raw
+     * `{ value, unit }` shape (a `toQuantity()` result, a quantity literal), so
+     * the analyzer must know them too or flag working navigation.
+     */
+    static SYSTEM_QUANTITY_ELEMENTS = new Map([
+        ['value', { types: ['System.Decimal'], isCollection: false, isChoice: false }],
+        ['unit', { types: ['System.String'], isCollection: false, isChoice: false }],
+    ]);
+    walkIdentifier(node, input) {
+        // Navigating from a statically empty input yields empty — nothing to check.
+        if (input.types !== undefined && input.types.length === 0) {
+            return { types: [], single: 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);
+            if (asType !== undefined) {
+                return { types: [asType], single: 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))) {
+                // 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)) {
+                    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;
+            }
+        }
+        const found = [];
+        let isCollection = false;
+        // Reference targets (Reference.targetProfile) accumulate so a later
+        // resolve() yields their union; one unconstrained reference makes the
+        // whole set unknown.
+        let targets = [];
+        for (const type of input.types) {
+            const element = type === 'System.Quantity'
+                ? Analyzer.SYSTEM_QUANTITY_ELEMENTS.get(node.name)
+                : this.model?.getElement(type, node.name);
+            if (element) {
+                // elementDependencies names model elements; System.Quantity's components
+                // are not ones (there is no FHIR `Quantity.value` dependency here).
+                if (!type.startsWith('System.')) {
+                    this.dependencies.add(`${typeLocalName(type)}.${node.name}`);
+                }
+                isCollection = isCollection || element.isCollection;
+                for (const elementType of element.types) {
+                    found.push(this.canonicalize(elementType));
+                }
+                if (element.types.some(elementType => typeLocalName(elementType) === 'Reference')) {
+                    targets = this.mergeTargets(targets, element);
+                }
+            }
+        }
+        if (found.length === 0) {
+            if (this.model) {
+                const hint = this.isChoiceKeyMisuse(input.types, node.name)
+                    ? '; choice elements use their stem name'
+                    : didYouMean(node.name, this.elementNames(input.types));
+                this.report('unknown-element', `Element '${node.name}' is not defined on ${input.types.join(' | ')}${hint}`, node.span, 'error', node.name);
+            }
+            return UNKNOWN;
+        }
+        const state = { types: [...new Set(found)], single: singleAnd(input.single, !isCollection) };
+        if (targets !== undefined && targets.length > 0) {
+            state.targets = [...new Set(targets)];
+        }
+        return state;
+    }
+    /**
+     * True when `canonical` is the model's Resource base or derives from it —
+     * the types whose instances carry a resourceType discriminator. A model
+     * without a Resource base cannot make the distinction, so the check stays
+     * permissive there.
+     */
+    isResourceType(canonical) {
+        const base = this.model?.resolveType('Resource');
+        return base === undefined || this.model?.isSubtypeOf(canonical, base) === true;
+    }
+    canonicalize(elementType) {
+        if (elementType.startsWith('System.')) {
+            return elementType;
+        }
+        return this.model?.resolveType(elementType) ?? elementType;
+    }
+    /**
+     * A Reference-typed element's targets folded into the accumulated set.
+     * One unconstrained reference makes the whole set unknown, and unknown
+     * stays unknown; otherwise the result is the canonicalized union.
+     */
+    mergeTargets(current, element) {
+        if (current === undefined || element.referenceTargets === undefined) {
+            return undefined;
+        }
+        return [...current, ...element.referenceTargets.map(target => this.canonicalize(target))];
+    }
+    /**
+     * True for `valueQuantity`-style keys whose stem is a choice element on one of the
+     * input types — the same test the evaluator uses (engine/navigation.ts), so the
+     * static diagnostic and the runtime error carry the same guidance.
+     */
+    isChoiceKeyMisuse(types, name) {
+        if (!this.model) {
+            return false;
+        }
+        for (const type of types) {
+            for (let position = 1; position < name.length; position++) {
+                if (!/[A-Z]/.test(name[position])) {
+                    continue;
+                }
+                const stem = name.slice(0, position);
+                if (this.model.getElement(type, stem)?.isChoice === true) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /** Every element name the input types can offer, for typo suggestions. */
+    elementNames(types) {
+        if (this.model?.listElements === undefined) {
+            return [];
+        }
+        const names = [];
+        for (const type of types) {
+            const elements = this.model.listElements(type);
+            if (elements !== undefined) {
+                names.push(...elements);
+            }
+        }
+        return names;
+    }
+    /**
+     * A call: resolve the function (built-ins first — EvaluateOptions.functions
+     * cannot override them either), then hand each concern to its own step:
+     * arity, input shape, arguments, per-function effects, result.
+     */
+    walkCall(node, input, scope) {
+        const registered = functions.get(node.name);
+        const custom = registered === undefined ? this.declarationFor(node.name, input) : undefined;
+        const resolved = registered ?? custom;
+        if (resolved === undefined) {
+            this.report('unknown-function', `Unrecognized function '${node.name}'${didYouMean(node.name, [...functions.keys(), ...this.customFunctions.keys()])}`, node.span, 'error', node.name);
+            this.walkUncheckedArguments(node, input, scope);
+            return UNKNOWN;
+        }
+        this.checkArity(node, resolved);
+        const signature = registered !== undefined ? FUNCTION_SIGNATURES[node.name] : this.toSignature(custom?.signature);
+        if (!signature) {
+            this.walkUncheckedArguments(node, input, scope);
+            return UNKNOWN;
+        }
+        this.checkCallInput(node, signature, input);
+        const { argStates, typeTarget } = this.walkArguments(node, signature, input, scope);
+        if (node.name === 'defineVariable') {
+            this.registerVariable(node, input, argStates, scope);
+        }
+        this.checkRegexPattern(node);
+        // ofType(X) filters and as(X) casts: both narrow to the named type,
+        // intersected with the known candidates.
+        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);
+    }
+    /**
+     * Selects a host declaration from the focus. One match keeps its full
+     * signature. Several matches are merged conservatively. No match merges their
+     * input types so `checkCallInput` can report one error.
+     */
+    declarationFor(name, input) {
+        const candidates = this.customFunctions.get(name);
+        if (candidates === undefined || candidates.length <= 1) {
+            return candidates?.[0];
+        }
+        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);
+    }
+    /** Without a signature the arguments still walk (for their own diagnostics), each in a scope fork. */
+    walkUncheckedArguments(node, input, scope) {
+        for (const argument of node.args) {
+            this.walk(argument, input, forkScope(scope));
+        }
+    }
+    checkArity(node, arity) {
+        const minArity = arity.minArity ?? 0;
+        const maxArity = arity.maxArity ?? Number.POSITIVE_INFINITY;
+        if (node.args.length < minArity || node.args.length > maxArity) {
+            this.report('wrong-arity', `Function '${node.name}' expects ${describeArity(minArity, maxArity)}, got ${node.args.length}`, node.span);
+        }
+    }
+    /** The signature's input constraints: cardinality, value kind, and declared types. */
+    checkCallInput(node, signature, input) {
+        if (!signature.input) {
+            return;
+        }
+        // A function written for one type (a DTO's `@column`), called on a focus
+        // that can never be that type. `unsatisfiedInput` holds the same rule the
+        // engine applies, so the two halves agree on what counts as a mistake.
+        const unsatisfied = input.types === undefined ? undefined : unsatisfiedInput(this.model, signature.input.types, input.types);
+        if (unsatisfied !== undefined) {
+            this.report('input-type', `${node.name}() expects ${unsatisfied.wanted.join(' | ')} as input, found ${unsatisfied.found.join(' | ')}`, node.span);
+        }
+        if (signature.input.singleton && input.types !== undefined && input.single === false) {
+            this.report('singleton-required', `${node.name}() expects a single item as input, but this is a collection (spec §11)${NARROW_HINT}`, node.span);
+        }
+        if (signature.input.kind) {
+            this.requireKind({ types: input.types, single: true }, signature.input.kind, node.span, `${node.name}() expects a ${signature.input.kind} input`);
+        }
+    }
+    /**
+     * Walk every argument per its spec — lambdas against a $this frame,
+     * type names against the model, values against $this — collecting the
+     * analyzed state per position (undefined for type-name positions). Each
+     * argument gets its own scope copy, like the runtime's per-argument fork.
+     */
+    walkArguments(node, signature, input, scope) {
+        const argStates = [];
+        let typeTarget;
+        node.args.forEach((argument, index) => {
+            const spec = signature.args?.[index] ?? signature.args?.at(-1);
+            if (spec === 'expression' || spec === 'condition' || spec === 'sort-key') {
+                // A top-level unary '-' on a sort key marks descending order (any type),
+                // mirroring how sort() reads the AST; only the key itself is analyzed.
+                const body = spec === 'sort-key' && argument.kind === 'unary' && argument.operator === '-' ? argument.operand : argument;
+                // $this is one item of the input — same candidates and reference targets.
+                const itemState = withSingle(input, true);
+                this.frames.push(itemState);
+                const state = this.walk(body, itemState, forkScope(scope));
+                this.frames.pop();
+                argStates.push(state);
+                if (spec === 'condition') {
+                    this.requireSingle(state, argument.span, `${node.name}() expects a single Boolean criterion`);
+                    if (!isCollection(state)) {
+                        this.requireKind(state, 'Boolean', argument.span, `${node.name}() expects a Boolean criterion`);
+                    }
+                }
+                return;
+            }
+            if (spec === 'type-name') {
+                argStates.push(undefined);
+                const resolved = this.checkTypeArgument(node.name, argument);
+                if (index === 0) {
+                    typeTarget = resolved;
+                }
+                return;
+            }
+            // Value arguments evaluate against $this, mirroring the runtime.
+            const argState = this.walk(argument, this.frames.at(-1) ?? this.rootState(), forkScope(scope));
+            argStates.push(argState);
+            if (spec !== undefined && spec !== 'any') {
+                if (argState.types !== undefined && argState.single === false) {
+                    this.report('argument-singleton', `${node.name}() expects a single ${spec} argument, but this is a collection (spec §11)${NARROW_HINT}`, argument.span, 'warning');
+                }
+                else {
+                    this.requireKind(argState, spec, argument.span, `${node.name}() expects a ${spec} argument`);
+                }
+            }
+        });
+        return { argStates, typeTarget };
+    }
+    /**
+     * The matches() family compiles its pattern with the backtracking JS RegExp,
+     * which cannot be timed out — flag exponential-shaped literal patterns.
+     */
+    checkRegexPattern(node) {
+        if (!REGEX_PATTERN_FUNCTIONS.has(node.name)) {
+            return;
+        }
+        const pattern = node.args[0];
+        if (pattern?.kind === 'string' && hasNestedUnboundedQuantifier(pattern.value)) {
+            this.report('regex-backtracking', `The regular expression nests unbounded repetition, which can backtrack catastrophically on non-matching input (ReDoS); rewrite it or supply a linear-time engine via EvaluateOptions.regex`, pattern.span, 'warning');
+        }
+    }
+    /**
+     * Track a defineVariable() binding in the chain's scope, with the same two
+     * rules the runtime enforces: no overriding environment variables, no
+     * redefining a name already in scope. Dynamic names cannot be tracked.
+     */
+    registerVariable(node, input, argStates, scope) {
+        const nameNode = node.args[0];
+        if (nameNode === undefined || nameNode.kind !== 'string') {
+            scope.hasDynamic = true;
+            return;
+        }
+        const name = nameNode.value;
+        if (BUILTIN_ENV_VARIABLE_NAMES.has(name) || this.declaredVariables.has(name)) {
+            this.report('variable-override', `Cannot override the environment variable %${name}`, nameNode.span);
+            return;
+        }
+        if (scope.vars.has(name)) {
+            this.report('variable-redefined', `Variable %${name} is already defined in this scope`, nameNode.span);
+            return;
+        }
+        // Without a value expression the variable holds the function's input.
+        scope.vars.set(name, argStates[1] ?? input);
+    }
+    /**
+     * Converts a host function's declared signature into the analyzer's internal
+     * shape. Result type names canonicalize once here, and a missing result stays
+     * unknown. The input passes through as declared, because `unsatisfiedInput`
+     * canonicalizes the names it compares, so a local name such as
+     * 'CodeableConcept' works without a second pass.
+     */
+    toSignature(declared) {
+        if (declared === undefined) {
+            return undefined;
+        }
+        const types = declared.result?.types?.map(type => this.canonicalize(type));
+        const single = declared.result?.single;
+        return {
+            ...(declared.input !== undefined && { input: declared.input }),
+            ...(declared.args !== undefined && { args: declared.args }),
+            result: () => ({ types, single }),
+        };
+    }
+    /**
+     * The candidate types that survive narrowing to `target`: subtypes of the
+     * target pass through unchanged, supertypes narrow to the target itself.
+     * Warns when no candidate can ever match — the result is provably empty.
+     */
+    narrowTypes(input, target, span) {
+        if (input.types === undefined) {
+            return [target];
+        }
+        const survivors = new Set();
+        for (const type of input.types) {
+            if (this.isTypeCompatible(type, target)) {
+                survivors.add(type);
+            }
+            else if (this.isTypeCompatible(target, type)) {
+                survivors.add(target);
+            }
+        }
+        if (survivors.size === 0 && input.types.length > 0) {
+            this.report('always-empty', `No candidate type (${input.types.join(' | ')}) can be a ${target}, so this is always empty`, span, 'warning');
+        }
+        return [...survivors];
+    }
+    /** True when every `type` value is a `base` value, including FHIR-primitive → System subtyping. */
+    isTypeCompatible(type, base) {
+        if (type === base || this.model?.isSubtypeOf(type, base) === true) {
+            return true;
+        }
+        return base.startsWith('System.') && FHIR_PRIMITIVE_TO_SYSTEM[typeLocalName(type)] === base;
+    }
+    /** Check a type-name argument; returns its canonical name, or undefined when unknown. */
+    checkTypeArgument(functionName, argument) {
+        const parts = typeSpecifierParts(argument);
+        if (parts === undefined) {
+            this.report('unknown-type', `${functionName}() expects a type name argument`, argument.span);
+            return undefined;
+        }
+        return this.checkTypeName(parts, argument.span);
+    }
+    /** 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])) {
+                this.report('unknown-type', `Unknown type 'System.${parts[1]}'`, span);
+                return undefined;
+            }
+            return `System.${parts[1]}`;
+        }
+        const name = parts.length === 2 ? parts[1] : parts[0];
+        if (parts.length === 2 && this.model && parts[0] !== this.model.namespace) {
+            this.report('unknown-type', `Unknown namespace '${parts[0]}'`, span);
+            return undefined;
+        }
+        const resolved = this.model?.resolveType(name);
+        if (this.model && resolved === undefined && !SYSTEM_TYPE_NAMES.has(name)) {
+            this.report('unknown-type', `Unknown type '${parts.join('.')}'`, span);
+            return undefined;
+        }
+        return resolved ?? (SYSTEM_TYPE_NAMES.has(name) ? `System.${name}` : name);
+    }
+    walkBinary(node, input, scope) {
+        // Operator operands are separate chains: each analyzes against its own scope
+        // copy, so defineVariable() in one side is invisible to the other, exactly
+        // like the runtime.
+        const left = this.walk(node.left, input, forkScope(scope));
+        const right = this.walk(node.right, input, forkScope(scope));
+        switch (node.operator) {
+            case '+':
+            case '-':
+            case '*':
+            case '/':
+            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 };
+            }
+            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 };
+            case '<':
+            case '>':
+            case '<=':
+            case '>=':
+                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 };
+            case '=':
+            case '!=':
+            case '~':
+            case '!~':
+                this.checkEquality(left, right, node.span);
+                return { types: ['System.Boolean'], single: true };
+            case 'and':
+            case 'or':
+            case 'xor':
+            case 'implies': {
+                // Any single item satisfies a Boolean operand through the implicit-exists
+                // 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 };
+            }
+            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);
+            }
+            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 };
+            }
+            /* v8 ignore start -- the parser produces no other binary operators */
+            default:
+                return UNKNOWN;
+            /* v8 ignore stop */
+        }
+    }
+    /** Report a singleton violation when the state is statically known to be a collection. */
+    requireSingle(state, span, message) {
+        if (isCollection(state)) {
+            this.report('singleton-required', `${message}${NARROW_HINT}`, span);
+        }
+    }
+    walkTypeOp(node, input, scope) {
+        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 };
+    }
+    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);
+        if (leftKind === undefined || rightKind === undefined || leftKind === 'Complex' || rightKind === 'Complex') {
+            return;
+        }
+        const scalars = ['Numeric', 'Quantity'];
+        const valid = (operator === '+' && leftKind === 'String' && rightKind === 'String') ||
+            ((operator === '+' || operator === '-') &&
+                ((leftKind === 'Numeric' && rightKind === 'Numeric') ||
+                    (leftKind === 'Quantity' && rightKind === 'Quantity') ||
+                    (leftKind === 'Temporal' && rightKind === 'Quantity'))) ||
+            ((operator === '*' || operator === '/') && scalars.includes(leftKind) && scalars.includes(rightKind)) ||
+            ((operator === 'div' || operator === 'mod') && leftKind === 'Numeric' && rightKind === 'Numeric');
+        if (!valid) {
+            this.report('operand-type', `Operator '${operator}' is not defined for these operand types`, span);
+        }
+    }
+    checkComparable(left, right, span) {
+        const leftKind = kindOf(left);
+        const rightKind = kindOf(right);
+        if (leftKind === undefined || rightKind === undefined) {
+            return;
+        }
+        if (leftKind === 'Boolean' || rightKind === 'Boolean' || leftKind !== rightKind) {
+            this.report('operand-type', 'Comparison operands must be single values of comparable types', span);
+        }
+    }
+    checkEquality(left, right, span) {
+        const leftKind = kindOf(left);
+        const rightKind = kindOf(right);
+        if (leftKind === undefined || rightKind === undefined || leftKind === 'Complex' || rightKind === 'Complex') {
+            return;
+        }
+        if (leftKind !== rightKind) {
+            this.report('equality-incompatible', `${leftKind} and ${rightKind} operands can never be equal (spec §11)`, span);
+        }
+    }
+    requireKind(state, kind, span, message) {
+        const actual = kindOf(state);
+        if (actual === undefined) {
+            return;
+        }
+        const compatible = actual === kind || (kind === 'Numeric' && actual === 'Quantity');
+        if (!compatible) {
+            this.report('operand-type', `${message}, found ${state.types?.join(' | ') ?? 'unknown'}`, span);
+        }
+    }
+    report(code, message, span, severity = 'error', name) {
+        this.diagnostics.push({ severity, code, message, span, ...(name !== undefined && { name }) });
+    }
+}
+/** 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) {
+    if (declared.expression === undefined) {
+        return declared;
+    }
+    // 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 }) };
+}
+/**
+ * What several declarations of one name say together, for a call none of them
+ * answers alone. Everything here widens: the arities span all of them, the
+ * input is every type any of them accepts, and the result is the union of
+ * theirs — unknown as soon as one declaration leaves it unknown. Arguments are
+ * dropped, since checking them against the wrong declaration would report valid
+ * code.
+ */
+function mergedDeclaration(candidates) {
+    const maxArity = Math.max(...candidates.map(candidate => candidate.maxArity ?? Number.POSITIVE_INFINITY));
+    const input = mergedInput(candidates);
+    const result = mergedResult(candidates);
+    return {
+        minArity: Math.min(...candidates.map(candidate => candidate.minArity ?? 0)),
+        ...(Number.isFinite(maxArity) && { maxArity }),
+        ...((input !== undefined || result !== undefined) && {
+            signature: { ...(input !== undefined && { input }), ...(result !== undefined && { result }) },
+        }),
+    };
+}
+/** Every type any declaration accepts, or undefined when one of them accepts anything. */
+function mergedInput(candidates) {
+    const declared = candidates.map(candidate => candidate.signature?.input?.types);
+    if (declared.some(types => types === undefined)) {
+        return undefined;
+    }
+    return { types: [...new Set(declared.flatMap(types => types ?? []))] };
+}
+/** 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,
+        single: candidate.signature?.result?.single,
+    })));
+    if (union.types === undefined && union.single === undefined) {
+        return undefined;
+    }
+    return {
+        ...(union.types !== undefined && { types: union.types }),
+        ...(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];
+    }
+    if (node.kind === 'dot' && node.left.kind === 'identifier' && node.right.kind === 'identifier') {
+        return [node.left.name, node.right.name];
+    }
+    return undefined;
+}
+/**
+ * `— did you mean 'X'?` for a mistyped name, or `''` when nothing is close enough.
+ */
+function didYouMean(target, candidates) {
+    const nearest = nearestName(target, candidates);
+    return nearest === undefined ? '' : ` — did you mean '${nearest}'?`;
+}
+/**
+ * The candidate `target` most plausibly misspells, or undefined when none is
+ * close enough: a small edit budget scaled to the name's length, so a genuine
+ * typo (`gven` → `given`, `lengthx` → `length`) matches while an unrelated name
+ * (`nope`) does not. Both the `did you mean` suggestions and `analyzeSite`
+ * weighing an unresolved column name go through here, so one budget decides what
+ * counts as a plausible misspelling.
+ */
+function nearestName(target, candidates) {
+    // Budget grows with the name: 1 edit for short names (<=4), up to 3 for long ones.
+    // Keeps suggestions high-precision — a real typo, not any name that happens to be near.
+    const budget = Math.min(3, Math.ceil(target.length / 4));
+    let best;
+    let bestDistance = budget + 1;
+    for (const candidate of candidates) {
+        if (candidate === target) {
+            continue;
+        }
+        // Only a strictly better distance matters, so the cap tightens as matches are found.
+        const limit = bestDistance - 1;
+        const distance = boundedEditDistance(target, candidate, limit);
+        if (distance <= limit) {
+            bestDistance = distance;
+            best = candidate;
+            if (bestDistance === 1) {
+                break; // Unbeatable: distance 0 would mean an exact match, which is skipped.
+            }
+        }
+    }
+    return best;
+}
+/**
+ * Levenshtein distance capped at `limit`: exact when the distance is <= limit,
+ * otherwise returns limit + 1. Only the |i - j| <= limit diagonal band of each
+ * DP row is computed (cells outside it can never end <= limit), and the scan
+ * bails as soon as a whole row exceeds the cap — so a non-match costs
+ * O(limit^2) instead of a full O(len(a) * len(b)) table.
+ */
+function boundedEditDistance(a, b, limit) {
+    if (Math.abs(a.length - b.length) > limit) {
+        return limit + 1;
+    }
+    const previous = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++) {
+        previous[j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        const from = Math.max(1, i - limit);
+        const to = Math.min(b.length, i + limit);
+        let diagonal = previous[from - 1];
+        previous[from - 1] = from === 1 ? i : limit + 1;
+        let rowBest = previous[from - 1];
+        for (let j = from; j <= to; j++) {
+            // The cell above sits outside the previous row's band when j = i + limit.
+            const above = j > i - 1 + limit ? limit + 1 : previous[j];
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const value = Math.min(above + 1, previous[j - 1] + 1, diagonal + cost);
+            previous[j] = value;
+            diagonal = above;
+            if (value < rowBest) {
+                rowBest = value;
+            }
+        }
+        if (rowBest > limit) {
+            return limit + 1;
+        }
+    }
+    return Math.min(previous[b.length], limit + 1);
+}
+//# sourceMappingURL=analyze.js.map