fhirpath-ts 0.0.0-bootstrap.0

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,296 @@
+# Third-party notices
+
+This package (`fhirpath-ts`) has **zero runtime dependencies**, but it
+contains material adapted from, or vendored out of, the projects below. This
+file consolidates their notices so any future redistribution of the package
+(npm publication, OSS extraction) carries them along. Today the package is
+consumed privately inside this repository.
+
+## Medplum — Apache License 2.0
+
+The Pratt-parser structure (prefix/infix parselets driven by a precedence
+table) in `src/parser/parser.ts` is adapted from Medplum's FHIRPath parser:
+<https://github.com/medplum/medplum> (`packages/core/src/fhirlexer/parse.ts`).
+A handful of evaluator spot-check expressions in
+`src/reference-crosschecks.test.ts` come from its test suite. Licensed under
+the Apache License 2.0 — full text in the appendix below.
+
+## octofhir/fhirpath-rs — Apache License 2.0
+
+Custom test cases in `src/reference-crosschecks.test.ts` are ported from
+<https://github.com/octofhir/fhirpath-rs> (`test-cases/groups/other/`),
+copyright (c) 2024 OctoFHIR Team. The project is dual-licensed MIT OR
+Apache-2.0; this package takes it under the Apache License 2.0 — full text in
+the appendix below.
+
+## FHIR/fhir-test-cases — Apache License 2.0
+
+The official FHIRPath conformance suites and their fixtures in
+`test-data/official/` are vendored (converted from XML to JSON) from
+<https://github.com/FHIR/fhir-test-cases>, licensed under the Apache License
+2.0 (also vendored alongside as `test-data/official/LICENSE.txt`). The FHIR®
+specification content they embed is offered by HL7 under CC0 terms.
+
+## HL7/fhirpath.js — NLM/Health Samurai license (BSD-style)
+
+The reference test corpus in `test-data/fhirpathjs/cases.json` and the
+fixtures in `test-data/fhirpathjs/resources/` are vendored (converted from
+YAML to JSON) from <https://github.com/HL7/fhirpath.js>. Some fixtures in
+`test-data/official/fixtures/` derive from the same project (see
+`test-data/official/FIXTURES-LICENSE.md`). Its license in full:
+
+> # LICENSE
+>
+> The software, fhirpath.js, was jointly developed by the Lister Hill National
+> Center for Biomedical Communications (LHNCBC), a research and development
+> division of the U.S. National Library of Medicine (NLM), and niquola@gmail.com
+> (Health Samurai).
+>
+> The following terms and conditions are based on the BSD open-source license.
+>
+> If publishing research that used this software, please include a citation that
+> acknowledges it.
+>
+> Redistribution and use in source and binary forms, with or without modification,
+> are permitted for commercial and non-commercial purposes and products alike,
+> provided that the following conditions are met:
+>
+>   * Redistributions of source code shall retain this license file, including the
+>   list of contributing developers and organizations, this list of conditions and
+>   the following disclaimer.
+>   * Redistributions in binary form shall include this license file, including the
+>   list of contributing developers and organizations, this list of conditions and
+>   the following disclaimer, in the documentation and/or other materials provided
+>   with the distribution.
+>   * Neither the names of the National Library of Medicine (NLM), the Lister Hill
+>   National Center for Biomedical Communications (LHNCBC), the National
+>   Institutes of Health (NIH), nor the names of any of the software contributors
+>   may be used to endorse or promote products derived from this software without
+>   specific prior written permission.
+>
+> THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS "AS IS" AND ANY EXPRESS
+> OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+> MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
+> SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+> SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+> PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+> BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+> CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+> IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
+> OF SUCH DAMAGE.
+
+## beda-software/fhirpath-py — MIT License
+
+The extra test cases in `test-data/fhirpathjs/cases-py-extras.json` are
+vendored (converted from YAML to JSON) from
+<https://github.com/beda-software/fhirpath-py>. Its license in full:
+
+> MIT License
+>
+> Copyright (c) 2020 beda.software
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+## HL7 FHIR® definitions — CC0
+
+The generated R4 model in `src/r4/generated/` is produced by
+`scripts/generate-r4-model.ts` from the HL7 FHIR R4 StructureDefinitions
+(shipped in `@medplum/definitions`). HL7 provides the FHIR specification
+content under Creative Commons "No Rights Reserved" (CC0). HL7®, FHIR® and
+the FHIR flame design are registered trademarks of Health Level Seven
+International; their use here is descriptive and implies no endorsement.
+
+## Appendix: Apache License 2.0
+
+Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+         Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+         stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+         that You distribute, all copyright, patent, trademark, and
+         attribution notices from the Source form of the Work,
+         excluding those notices that do not pertain to any part of
+         the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+         distribution, then any Derivative Works that You distribute must
+         include a readable copy of the attribution notices contained
+         within such NOTICE file, excluding those notices that do not
+         pertain to any part of the Derivative Works, in at least one
+         of the following places: within a NOTICE text file distributed
+         as part of the Derivative Works; within the Source form or
+         documentation, if provided along with the Derivative Works; or,
+         within a display generated by the Derivative Works, if and
+         wherever such third-party notices normally appear. The contents
+         of the NOTICE file are for informational purposes only and
+         do not modify the License. You may add Your own attribution
+         notices within Derivative Works that You distribute, alongside
+         or as an addendum to the NOTICE text from the Work, provided
+         that such additional attribution notices cannot be construed
+         as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/dist/analyzer/analyze-dto.d.ts

@@ -0,0 +1,45 @@
+import { type DtoClass } from '../api/dto.ts';
+import type { ModelProvider } from '../model/provider.ts';
+import { type AnalyzeOptions, type AnalyzerDiagnostic, type DeclaredFunction } from './analyze.ts';
+/** One `analyzeDto` finding: an analyzer diagnostic plus the class member it came from. */
+export interface DtoDiagnostic extends AnalyzerDiagnostic {
+    /** The column field name, or `vars.<name>` for a DTO var. */
+    member: string;
+    /** The expression that produced the finding, so a reporter can locate it in source. */
+    expression: string;
+}
+/** Engine context read by the analyzer without importing the engine implementation. */
+export interface AnalyzedContext {
+    readonly defaults: {
+        model?: ModelProvider;
+        functions?: Record<string, DeclaredFunction>;
+        env?: object;
+    };
+}
+/** A context that also knows which DTOs it registered, which is what a sweep needs. */
+export interface AnalyzedEngine extends AnalyzedContext {
+    readonly dtos: readonly DtoClass[];
+}
+/** `analyzeDto` options, with the engine the DTO belongs to as a shortcut for its context. */
+export interface AnalyzeDtoOptions extends AnalyzeOptions {
+    /** Engine model, functions, and environment names used while checking the DTO. */
+    engine?: AnalyzedContext;
+}
+/**
+ * Every DTO an engine registered, checked against that engine's own context —
+ * the sweep a project's checker runs, with no list to maintain: the engine
+ * already knows its `resourceDtos`. Each finding names the class it came from.
+ * DTOs the engine does not register (row shapes you only ever project) are not
+ * reachable from here; pass those to `analyzeDto` yourself, or list them.
+ */
+export declare function analyzeEngineDtos(engine: AnalyzedEngine, options?: AnalyzeOptions): (DtoDiagnostic & {
+    dto: string;
+})[];
+/**
+ * Checks a DTO's columns, criteria, and variables. The DTO type is the input
+ * context. DTO environment names, caller environment names, and row variables
+ * are declared automatically. Variables are checked in order. Declared column
+ * types and enums are compared with the analyzer result.
+ */
+export declare function analyzeDto(dto: DtoClass, options?: AnalyzeDtoOptions): DtoDiagnostic[];
+//# sourceMappingURL=analyze-dto.d.ts.map

package/dist/analyzer/analyze-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-dto.d.ts","sourceRoot":"","sources":["../../src/analyzer/analyze-dto.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,QAAQ,EAAiB,MAAM,eAAe,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAA;AAErB,2FAA2F;AAC3F,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACvD,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE;QAAE,KAAK,CAAC,EAAE,aAAa,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACzG;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAA;CACnC;AAED,8FAA8F;AAC9F,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,kFAAkF;IAClF,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAgCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,CAAC,aAAa,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,CAIrC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,EAAE,CA+CtF"}

package/dist/analyzer/analyze-dto.js

@@ -0,0 +1,147 @@
+import { columnResultType } from "../api/column-signature.js";
+import { dtoDefinition } from "../api/dto.js";
+import { valueKindOfTypeName } from "../values/type-compat.js";
+import { analyzeExpressionDetailed, } from "./analyze.js";
+/**
+ * The analyzer context for a DTO: what its engine supplies, with the caller's
+ * own options layered on top *per name* — one function or variable a host
+ * declares must not displace the engine's whole table, or a valid column call
+ * would be reported as unresolved. `model` and `inputType` are single values, so
+ * there the caller simply wins.
+ */
+function contextOf(options) {
+    const { engine, ...caller } = options ?? {};
+    if (engine === undefined) {
+        return caller;
+    }
+    const { model, functions, env } = engine.defaults;
+    return {
+        ...(model !== undefined && { model }),
+        ...caller,
+        functions: { ...functions, ...caller.functions },
+        variables: { ...envVariables(env), ...caller.variables },
+    };
+}
+/** An engine's env names, declared as variables the expressions may read. */
+function envVariables(env) {
+    const variables = {};
+    for (const name of Object.keys(env ?? {})) {
+        variables[bare(name)] = {};
+    }
+    return variables;
+}
+/**
+ * Every DTO an engine registered, checked against that engine's own context —
+ * the sweep a project's checker runs, with no list to maintain: the engine
+ * already knows its `resourceDtos`. Each finding names the class it came from.
+ * DTOs the engine does not register (row shapes you only ever project) are not
+ * reachable from here; pass those to `analyzeDto` yourself, or list them.
+ */
+export function analyzeEngineDtos(engine, options) {
+    return engine.dtos.flatMap(dto => analyzeDto(dto, { ...options, engine }).map(finding => ({ ...finding, dto: dto.name })));
+}
+/**
+ * Checks a DTO's columns, criteria, and variables. The DTO type is the input
+ * context. DTO environment names, caller environment names, and row variables
+ * are declared automatically. Variables are checked in order. Declared column
+ * types and enums are compared with the analyzer result.
+ */
+export function analyzeDto(dto, options) {
+    const definition = dtoDefinition(dto);
+    const context = contextOf(options);
+    const inputType = context.inputType ?? definition.fhirType;
+    const declared = {
+        rowIndex: { types: ['System.Integer'], single: true },
+        rowTotal: { types: ['System.Integer'], single: true },
+    };
+    for (const name of [...Object.keys(definition.env ?? {}), ...(definition.callerEnv ?? [])]) {
+        declared[bare(name)] = {};
+    }
+    const diagnostics = [];
+    const analyze = (member, expression, column) => {
+        const perExpression = {
+            ...context,
+            ...(inputType !== undefined && { inputType }),
+            variables: { ...declared, ...context.variables },
+        };
+        const { diagnostics: found, result } = analyzeExpressionDetailed(expression, perExpression);
+        for (const diagnostic of found) {
+            diagnostics.push({ member, expression, ...diagnostic });
+        }
+        const mismatch = column === undefined ? undefined : declaredTypeMismatch(column, result.types, context);
+        if (mismatch !== undefined) {
+            // The conflicting field declaration is outside the expression, so mark the whole expression.
+            diagnostics.push({
+                member,
+                expression,
+                severity: 'error',
+                code: 'column-type',
+                message: mismatch,
+                span: { start: 0, end: expression.length, line: 1, column: 1 },
+            });
+        }
+    };
+    for (const [name, value] of Object.entries(definition.vars ?? {})) {
+        const source = typeof value === 'string' ? value : sourceOf(value);
+        if (source !== undefined) {
+            // A var declares no type, so there is nothing to cross-check against.
+            analyze(`vars.${bare(name)}`, source);
+        }
+        declared[bare(name)] = {};
+    }
+    for (const [name, spec] of Object.entries(definition.columns)) {
+        analyze(name, expressionOf(spec), spec);
+    }
+    return diagnostics;
+}
+/** The expression a column reads: a criteria's `test`, else its path. */
+function expressionOf(column) {
+    return 'test' in column ? column.test : column.path;
+}
+/**
+ * The type a column claims its expression yields — `columnSignature`'s rule, the
+ * one the engine registers and the walkers declare, so a cross-check can never
+ * contradict a claim that was never made.
+ *
+ * A criteria claims nothing here, even though its function declares a Boolean
+ * result. The Boolean comes from the criteria rule applied to the result, not
+ * from the expression itself. `@criteria('name.given')` validly returns
+ * HumanName.given, which then reads as true.
+ */
+function claimedType(column) {
+    return 'test' in column ? undefined : columnResultType(column);
+}
+/**
+ * Compares a declared column type with analyzer results. Primitive types compare
+ * by value kind; complex types use the model hierarchy. Unknown results pass.
+ */
+function declaredTypeMismatch(column, yielded, options) {
+    const claimed = claimedType(column);
+    if (claimed === undefined || yielded === undefined || yielded.length === 0) {
+        return undefined;
+    }
+    const canonical = options?.model?.resolveType(claimed) ?? claimed;
+    const claimedKind = valueKindOfTypeName(canonical);
+    const fits = yielded.some(type => {
+        if (valueKindOfTypeName(type) !== claimedKind) {
+            return false;
+        }
+        if (claimedKind !== 'Complex') {
+            return true;
+        }
+        const model = options?.model;
+        /* v8 ignore next -- without a model the analyzer never reaches a complex FHIR type, so the model-less half cannot be exercised */
+        return model === undefined || model.isSubtypeOf(type, canonical) || model.isSubtypeOf(canonical, type);
+    });
+    return fits ? undefined : `Column declares type '${claimed}', but the expression yields ${yielded.join(' | ')}`;
+}
+const bare = (name) => (name.startsWith('%') ? name.slice(1) : name);
+/** A pre-compiled var's source text; a pre-bound TypedValue[] has nothing to analyze. */
+function sourceOf(value) {
+    if (Array.isArray(value)) {
+        return undefined;
+    }
+    const source = value.source;
+    return typeof source === 'string' ? source : undefined;
+}
+//# sourceMappingURL=analyze-dto.js.map

package/dist/analyzer/analyze-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-dto.js","sourceRoot":"","sources":["../../src/analyzer/analyze-dto.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/analyze.d.ts

@@ -0,0 +1,98 @@
+import '../functions/install.ts';
+import { type SourceSpan } from '../errors.ts';
+import type { ModelProvider } from '../model/provider.ts';
+import { type CustomFunctionSignature } from './signatures.ts';
+export interface AnalyzerDiagnostic {
+    severity: 'error' | 'warning';
+    /** Unresolved element, function, or variable name, when the diagnostic has one. */
+    name?: string;
+    /** Stable rule identifier, e.g. `unknown-element` or `singleton-required`. */
+    code: string;
+    message: string;
+    span: SourceSpan;
+}
+/** A host variable known to the analyzer. Omit its types to keep the value unknown. */
+export interface DeclaredVariable {
+    /** Candidate type names ('Patient', 'System.String'); omit to leave the type unknown. */
+    types?: string[];
+    /** True when the variable always holds at most one item. */
+    single?: boolean;
+}
+/** A host function declaration. Arity resolves the call; an optional signature checks it. */
+export type SingleDeclaredFunction = {
+    minArity?: number;
+    maxArity?: number;
+    expression?: never;
+    signature?: CustomFunctionSignature;
+} | {
+    /** The body of an expression-defined CustomFunction; its presence pins the arity to 0. */
+    expression: unknown;
+    minArity?: never;
+    maxArity?: never;
+    signature?: CustomFunctionSignature;
+};
+/** Same-name functions selected by the call focus. Unknown focus keeps only their shared claims. */
+export interface OverloadedDeclaredFunction {
+    overloads: readonly SingleDeclaredFunction[];
+    expression?: never;
+    minArity?: never;
+    maxArity?: never;
+    signature?: never;
+}
+export type DeclaredFunction = SingleDeclaredFunction | OverloadedDeclaredFunction;
+export interface AnalyzeOptions {
+    model?: ModelProvider;
+    /** Canonical type of the input the expression will run against, e.g. `FHIR.Patient` or `Patient`. */
+    inputType?: string;
+    /** Host-supplied functions by name — EvaluateOptions.functions can be passed as-is. */
+    functions?: Record<string, DeclaredFunction>;
+    /** Host-supplied environment variables by name (with or without the leading `%`). */
+    variables?: Record<string, DeclaredVariable>;
+}
+export interface AnalysisDetails {
+    diagnostics: AnalyzerDiagnostic[];
+    /**
+     * The expression's inferred result: canonical type names and cardinality, the
+     * same StaticState the checks run on. `types: undefined` means the analyzer
+     * cannot see through the expression (an unknown region), and `single`
+     * undefined means the cardinality is unknown — neither is an error. Lets a
+     * caller cross-check a declared type against what the expression really
+     * yields (see `analyzeDto`).
+     */
+    result: {
+        types: string[] | undefined;
+        single: boolean | undefined;
+    };
+    /**
+     * `Type.element` paths the expression reads (local type names), deduped in
+     * first-visit order — HAPI's `elementDependencies`. Lets callers know which
+     * elements an expression depends on, e.g. for change tracking or editors.
+     */
+    elementDependencies: string[];
+}
+/**
+ * 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 declare function analyzeExpression(expression: string, options?: AnalyzeOptions): AnalyzerDiagnostic[];
+/**
+ * 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 declare function analyzeSite(site: {
+    expression: string;
+    inputType?: string;
+    dto?: true;
+    /** Functions the site's file declares — a DTO's `@column` fields (see `columnFunctionDeclaration`). */
+    functions?: Readonly<Record<string, DeclaredFunction>>;
+}, options?: AnalyzeOptions): AnalyzerDiagnostic[];
+/** `analyzeExpression` plus the element paths the expression touches and its inferred result type. */
+export declare function analyzeExpressionDetailed(expression: string, options?: AnalyzeOptions): AnalysisDetails;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyzer/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyzer/analyze.ts"],"names":[],"mappings":"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"}