fhir-runtime 0.2.0

package/dist/lib/profile/element-merger.d.ts

@@ -0,0 +1,80 @@
+/**
+ * fhir-profile — Element Merger (Core Merge Loop)
+ *
+ * Implements the base-driven merge loop for snapshot generation,
+ * corresponding to HAPI FHIR R4's `ProfileUtilities.processPaths()`.
+ *
+ * This is the **core engine** of snapshot generation. It walks the base
+ * snapshot element-by-element, finds matching differential entries, and
+ * produces the merged snapshot output.
+ *
+ * Four major branches:
+ * - **Branch A**: No diff match → inherit base as-is (may recurse for inner diffs)
+ * - **Branch B**: Single diff match → merge constraints, recurse into children/datatype
+ * - **Branch C**: Type slicing → multiple diffs constrain different types
+ * - **Branch D**: Explicit slicing → multiple diffs with sliceNames
+ *
+ * @module fhir-profile
+ */
+import type { ElementDefinition } from '../model/index.js';
+import type { FhirContext } from '../context/types.js';
+import type { DiffElementTracker, SnapshotIssue } from './types.js';
+/**
+ * Shared state passed through all recursive `processPaths` calls.
+ */
+export interface MergeContext {
+    /** FhirContext for loading datatype definitions (async). `undefined` for sync-only tests. */
+    readonly fhirContext?: FhirContext;
+    /** Preloaded datatype snapshots cache (url → snapshot elements). */
+    readonly datatypeCache: Map<string, readonly ElementDefinition[]>;
+    /** Issue collector. */
+    readonly issues: SnapshotIssue[];
+    /** URL of the profile being generated. */
+    readonly profileUrl: string;
+    /** Current recursion depth. */
+    depth: number;
+    /** Maximum allowed recursion depth. */
+    readonly maxDepth: number;
+}
+/**
+ * Create a default MergeContext.
+ */
+export declare function createMergeContext(profileUrl: string, options?: {
+    fhirContext?: FhirContext;
+    maxDepth?: number;
+}): MergeContext;
+/**
+ * Base-driven merge loop (corresponds to HAPI `processPaths`).
+ *
+ * Walks the base snapshot within `baseScope`, finds matching differential
+ * entries within `[diffStart, diffEnd]`, and appends merged elements to `result`.
+ *
+ * @param context - Shared merge state.
+ * @param result - Mutable output array to append merged elements to.
+ * @param baseElements - The base snapshot element list.
+ * @param baseCursor - Start index in baseElements (inclusive).
+ * @param baseLimit - End index in baseElements (inclusive).
+ * @param diffTrackers - The differential element trackers.
+ * @param diffStart - Start index in diffTrackers (inclusive).
+ * @param diffEnd - End index in diffTrackers (inclusive).
+ * @param contextPathSrc - Source path prefix for rewriting (e.g., datatype name).
+ * @param contextPathDst - Destination path prefix for rewriting.
+ */
+export declare function processPaths(context: MergeContext, result: ElementDefinition[], baseElements: readonly ElementDefinition[], baseCursor: number, baseLimit: number, diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string): void;
+/**
+ * High-level convenience function: merge a base snapshot with a differential
+ * to produce a new snapshot element list.
+ *
+ * This is the primary entry point for testing and for the SnapshotGenerator
+ * orchestrator (Task 4.5).
+ *
+ * @param baseElements - The base profile's snapshot elements.
+ * @param diffElements - The differential elements to apply.
+ * @param context - Merge context (or auto-created if not provided).
+ * @returns The merged snapshot element list.
+ */
+export declare function mergeSnapshot(baseElements: readonly ElementDefinition[], diffElements: readonly ElementDefinition[], context?: MergeContext): {
+    elements: ElementDefinition[];
+    issues: SnapshotIssue[];
+};
+//# sourceMappingURL=element-merger.d.ts.map

package/dist/lib/profile/element-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-merger.d.ts","sourceRoot":"","sources":["../../../src/profile/element-merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAiBpF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAClE,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,YAAY,CASd;AAuBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,iBAAiB,EAAE,EAC3B,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,IAAI,CAsLN;AAqgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,OAAO,CAAC,EAAE,YAAY,GACrB;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CAiC5D"}

package/dist/lib/profile/element-sorter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * fhir-profile — Element Sorter
+ *
+ * Sorting and ordering utilities for snapshot generation.
+ * Corresponds to HAPI FHIR R4's `sortDifferential()` + `sortElements()`.
+ *
+ * Key concepts:
+ * - The authoritative order is the **base snapshot element order**, not alphabetical
+ * - Differential elements may need pre-sorting before merge
+ * - Sorting builds a tree, sorts each level by base index, then flattens
+ *
+ * Exported functions:
+ * - {@link sortDifferential} — sort diff elements by base snapshot order
+ * - {@link findBaseIndex} — locate a path in the base snapshot
+ * - {@link validateElementOrder} — verify snapshot ordering post-generation
+ * - {@link ensureElementIds} — generate element IDs from path + sliceName
+ *
+ * @module fhir-profile
+ */
+import type { ElementDefinition } from '../model/index.js';
+import type { SnapshotIssue } from './types.js';
+/**
+ * Find the index of a path in the base snapshot.
+ *
+ * Handles:
+ * - Exact path match
+ * - Choice type match (e.g., `valueString` matches `value[x]`)
+ * - Slice paths (strips `:sliceName` from id to match by path)
+ *
+ * @param baseSnapshot - The base snapshot element list.
+ * @param path - The path to find.
+ * @param sliceName - Optional slice name for disambiguation.
+ * @returns The index in baseSnapshot, or -1 if not found.
+ */
+export declare function findBaseIndex(baseSnapshot: readonly ElementDefinition[], path: string, sliceName?: string): number;
+/**
+ * Sort differential elements according to base snapshot order.
+ *
+ * Corresponds to HAPI's `sortDifferential()`. The algorithm:
+ * 1. Build a tree from the differential elements (parent-child by path)
+ * 2. Assign each node a base index via {@link findBaseIndex}
+ * 3. Sort children at each level by base index
+ * 4. Flatten the tree back to a linear list
+ *
+ * Elements not found in the base are placed at the end of their level
+ * and an issue is recorded.
+ *
+ * @param differential - The differential elements to sort (not mutated).
+ * @param baseSnapshot - The base snapshot providing the authoritative order.
+ * @param issues - Issue collector for recording problems.
+ * @returns A new array of elements in sorted order.
+ */
+export declare function sortDifferential(differential: readonly ElementDefinition[], baseSnapshot: readonly ElementDefinition[], issues: SnapshotIssue[]): ElementDefinition[];
+/**
+ * Validate that snapshot elements are in correct order.
+ *
+ * Rules:
+ * - Parent elements must appear before their children
+ * - Slice elements must appear after their slicing root
+ * - No duplicate paths (unless sliced)
+ *
+ * @param snapshot - The snapshot elements to validate.
+ * @param issues - Issue collector for recording problems.
+ * @returns `true` if order is valid, `false` if any violations found.
+ */
+export declare function validateElementOrder(snapshot: readonly ElementDefinition[], issues: SnapshotIssue[]): boolean;
+/**
+ * Ensure all elements have an `id` property.
+ *
+ * If an element lacks an `id`, generates one from its path and sliceName.
+ * This follows the FHIR convention:
+ * - Unsliced: `id = path` (e.g., `"Patient.name"`)
+ * - Sliced: `id = path:sliceName` (e.g., `"Patient.identifier:MRN"`)
+ *
+ * Corresponds to HAPI's `setIds()`.
+ *
+ * @param elements - The elements to process (mutated in place).
+ * @param resourceType - The resource type name (used for the root element).
+ */
+export declare function ensureElementIds(elements: ElementDefinition[], resourceType?: string): void;
+//# sourceMappingURL=element-sorter.d.ts.map

package/dist/lib/profile/element-sorter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-sorter.d.ts","sourceRoot":"","sources":["../../../src/profile/element-sorter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6BhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CA2BR;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,YAAY,EAAE,SAAS,iBAAiB,EAAE,EAC1C,MAAM,EAAE,aAAa,EAAE,GACtB,iBAAiB,EAAE,CA+ErB;AAoDD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,MAAM,EAAE,aAAa,EAAE,GACtB,OAAO,CAmDT;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,YAAY,CAAC,EAAE,MAAM,GACpB,IAAI,CAiBN"}

package/dist/lib/profile/errors.d.ts

@@ -0,0 +1,150 @@
+/**
+ * fhir-profile — Error Types
+ *
+ * Structured error hierarchy for the FHIR profile module.
+ * All errors extend {@link ProfileError} so consumers can catch
+ * profile-related failures with a single `catch` clause.
+ *
+ * Error hierarchy:
+ * ```
+ * ProfileError (base)
+ * ├── SnapshotCircularDependencyError
+ * ├── BaseNotFoundError
+ * ├── ConstraintViolationError
+ * └── UnconsumedDifferentialError
+ * ```
+ *
+ * @module fhir-profile
+ */
+/**
+ * Base error class for all fhir-profile failures.
+ *
+ * Provides a stable `name` property and preserves the original `cause`
+ * when wrapping lower-level errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await generator.generate(sd);
+ * } catch (err) {
+ *   if (err instanceof ProfileError) {
+ *     // Handle any profile-related error
+ *   }
+ * }
+ * ```
+ */
+export declare class ProfileError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when snapshot generation detects a circular dependency in the
+ * profile chain.
+ *
+ * This occurs when profile A's base chain eventually references A again,
+ * which would cause infinite recursion during snapshot generation.
+ * HAPI detects this via a `snapshotStack` of URLs currently being generated.
+ *
+ * @example
+ * ```typescript
+ * throw new SnapshotCircularDependencyError(
+ *   'http://example.org/ProfileA',
+ *   [
+ *     'http://example.org/ProfileA',
+ *     'http://example.org/ProfileB',
+ *     'http://example.org/ProfileA', // cycle back
+ *   ]
+ * );
+ * ```
+ */
+export declare class SnapshotCircularDependencyError extends ProfileError {
+    readonly name = "SnapshotCircularDependencyError";
+    /** The canonical URL of the profile that triggered the cycle. */
+    readonly url: string;
+    /** The full chain of URLs forming the cycle. */
+    readonly chain: readonly string[];
+    constructor(url: string, chain: string[]);
+}
+/**
+ * Thrown when the base StructureDefinition required for snapshot generation
+ * cannot be loaded from any source.
+ *
+ * This is a fatal error — snapshot generation cannot proceed without the
+ * base profile's snapshot to merge against.
+ *
+ * @example
+ * ```typescript
+ * throw new BaseNotFoundError(
+ *   'http://hl7.org/fhir/StructureDefinition/Patient',
+ *   'http://hl7.org/fhir/StructureDefinition/UnknownBase'
+ * );
+ * ```
+ */
+export declare class BaseNotFoundError extends ProfileError {
+    readonly name = "BaseNotFoundError";
+    /** The canonical URL of the derived profile being generated. */
+    readonly derivedUrl: string;
+    /** The canonical URL of the base that could not be found. */
+    readonly baseUrl: string;
+    constructor(derivedUrl: string, baseUrl: string, cause?: Error);
+}
+/**
+ * Thrown when constraint merging detects an illegal tightening or
+ * incompatible constraint.
+ *
+ * This covers violations such as:
+ * - Cardinality loosening (`derived.min < base.min`)
+ * - Cardinality widening (`derived.max > base.max`)
+ * - Type expansion (derived types not a subset of base types)
+ * - Binding relaxation (relaxing a REQUIRED binding)
+ *
+ * Only thrown when {@link SnapshotGeneratorOptions.throwOnError} is `true`.
+ * Otherwise, violations are recorded as issues in the result.
+ *
+ * @example
+ * ```typescript
+ * throw new ConstraintViolationError(
+ *   'CARDINALITY_VIOLATION',
+ *   'Patient.identifier',
+ *   'Derived min (0) is less than base min (1)'
+ * );
+ * ```
+ */
+export declare class ConstraintViolationError extends ProfileError {
+    readonly name = "ConstraintViolationError";
+    /** The type of constraint violation. */
+    readonly violationType: string;
+    /** The element path where the violation occurred. */
+    readonly path: string;
+    constructor(violationType: string, path: string, message: string);
+}
+/**
+ * Thrown when differential elements remain unconsumed after snapshot
+ * generation completes.
+ *
+ * This indicates that the algorithm could not find a matching base
+ * element for one or more differential entries. Common causes:
+ * - Incorrect path in differential
+ * - Slicing mismatch
+ * - Unsupported constraint pattern
+ *
+ * HAPI detects this via the `GENERATED_IN_SNAPSHOT` marker pattern.
+ *
+ * Only thrown when {@link SnapshotGeneratorOptions.throwOnError} is `true`.
+ * Otherwise, each unconsumed element is recorded as an issue.
+ *
+ * @example
+ * ```typescript
+ * throw new UnconsumedDifferentialError([
+ *   'Patient.nonExistentField',
+ *   'Patient.identifier:BadSlice',
+ * ]);
+ * ```
+ */
+export declare class UnconsumedDifferentialError extends ProfileError {
+    readonly name = "UnconsumedDifferentialError";
+    /** Paths of the unconsumed differential elements. */
+    readonly unconsumedPaths: readonly string[];
+    constructor(unconsumedPaths: string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/profile/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/profile/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,EAAE,MAAM,CAAkB;gBAEpC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpD;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,+BAAgC,SAAQ,YAAY;IAC/D,SAAkB,IAAI,qCAAqC;IAE3D,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEtB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;CAMzC;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,SAAkB,IAAI,uBAAuB;IAE7C,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAQ/D;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAyB,SAAQ,YAAY;IACxD,SAAkB,IAAI,8BAA8B;IAEpD,wCAAwC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjE;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,2BAA4B,SAAQ,YAAY;IAC3D,SAAkB,IAAI,iCAAiC;IAEvD,qDAAqD;IACrD,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;gBAEhC,eAAe,EAAE,MAAM,EAAE;CAStC"}

package/dist/lib/profile/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * fhir-profile — Barrel Exports
+ *
+ * Re-exports all public types, interfaces, error classes, and helper
+ * functions from the FHIR profile module.
+ *
+ * Public surface:
+ * - Types: SnapshotGeneratorOptions, SnapshotResult, SnapshotIssue, etc.
+ * - SnapshotGenerator: orchestrator class
+ * - CanonicalBuilder: SD → CanonicalProfile conversion
+ * - Errors: ProfileError hierarchy
+ * - Path Utilities: path matching for advanced consumers
+ *
+ * @module fhir-profile
+ */
+export type { SnapshotGeneratorOptions, SnapshotResult, SnapshotIssue, SnapshotIssueCode, DiffElementTracker, TraversalScope, } from './types.js';
+export { createSnapshotIssue, createDiffTracker, } from './types.js';
+export { SnapshotGenerator } from './snapshot-generator.js';
+export { buildCanonicalProfile, buildCanonicalElement, buildTypeConstraints, buildBindingConstraint, buildInvariants, buildSlicingDefinition, } from './canonical-builder.js';
+export { ProfileError, SnapshotCircularDependencyError, BaseNotFoundError, ConstraintViolationError, UnconsumedDifferentialError, } from './errors.js';
+export { pathMatches, isDirectChild, isDescendant, pathDepth, parentPath, tailSegment, isChoiceTypePath, matchesChoiceType, extractChoiceTypeName, hasSliceName, extractSliceName, } from './path-utils.js';
+export { findBaseIndex, sortDifferential, validateElementOrder, ensureElementIds, } from './element-sorter.js';
+export { mergeConstraints, setBaseTraceability, mergeCardinality, mergeTypes, mergeBinding, mergeConstraintList, isLargerMax, } from './constraint-merger.js';
+export type { MergeContext } from './element-merger.js';
+export { createMergeContext, processPaths, mergeSnapshot, } from './element-merger.js';
+export { makeExtensionSlicing, getSliceSiblings, validateSlicingCompatibility, diffsConstrainTypes, handleNewSlicing, handleExistingSlicing, } from './slicing-handler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/profile/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/profile/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,YAAY,EACV,wBAAwB,EACxB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,YAAY,EACZ,+BAA+B,EAC/B,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,aAAa,EACb,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAGhC,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,4BAA4B,EAC5B,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC"}

package/dist/lib/profile/path-utils.d.ts

@@ -0,0 +1,180 @@
+/**
+ * fhir-profile — Path Utility Functions
+ *
+ * Path matching and manipulation utilities used by the snapshot generation
+ * algorithm. These functions underpin the base-driven traversal in
+ * {@link ElementMerger} (the `processPaths` equivalent).
+ *
+ * Key concepts:
+ * - **Element path**: dot-separated segments like `"Patient.name.given"`
+ * - **Choice type path**: ends with `[x]`, e.g. `"Observation.value[x]"`
+ * - **Concrete choice path**: resolved form, e.g. `"Observation.valueString"`
+ * - **Slice name**: stored in element id with `:` separator, e.g. `"Patient.identifier:MRN"`
+ *
+ * @module fhir-profile
+ */
+import type { ElementDefinition } from '../model/index.js';
+import type { DiffElementTracker, TraversalScope } from './types.js';
+/**
+ * Check whether two paths match exactly.
+ *
+ * @example
+ * pathMatches('Patient.name', 'Patient.name')       // true
+ * pathMatches('Patient.name', 'Patient.identifier')  // false
+ */
+export declare function pathMatches(basePath: string, diffPath: string): boolean;
+/**
+ * Check whether `childPath` is a direct child of `parentPath`.
+ *
+ * A direct child has exactly one more segment than the parent.
+ *
+ * @example
+ * isDirectChild('Patient.name', 'Patient.name.given')       // true
+ * isDirectChild('Patient.name', 'Patient.name.given.value')  // false
+ * isDirectChild('Patient.name', 'Patient.identifier')        // false
+ */
+export declare function isDirectChild(parentPath: string, childPath: string): boolean;
+/**
+ * Check whether `descendantPath` is a descendant of `ancestorPath`
+ * (at any depth).
+ *
+ * @example
+ * isDescendant('Patient.name', 'Patient.name.given')        // true
+ * isDescendant('Patient.name', 'Patient.name.given.value')  // true
+ * isDescendant('Patient.name', 'Patient.name')              // false
+ * isDescendant('Patient.name', 'Patient.identifier')        // false
+ */
+export declare function isDescendant(ancestorPath: string, descendantPath: string): boolean;
+/**
+ * Get the depth (number of segments) of a path.
+ *
+ * @example
+ * pathDepth('Patient')             // 1
+ * pathDepth('Patient.name')        // 2
+ * pathDepth('Patient.name.given')  // 3
+ */
+export declare function pathDepth(path: string): number;
+/**
+ * Get the parent path (everything before the last `.`).
+ *
+ * @example
+ * parentPath('Patient.name.given')  // 'Patient.name'
+ * parentPath('Patient.name')        // 'Patient'
+ * parentPath('Patient')             // undefined
+ */
+export declare function parentPath(path: string): string | undefined;
+/**
+ * Get the last segment (tail) of a path.
+ *
+ * @example
+ * tailSegment('Patient.name.given')  // 'given'
+ * tailSegment('Patient')             // 'Patient'
+ */
+export declare function tailSegment(path: string): string;
+/**
+ * Check whether a path ends with `[x]` (choice type wildcard).
+ *
+ * @example
+ * isChoiceTypePath('Observation.value[x]')  // true
+ * isChoiceTypePath('Observation.valueString')  // false
+ * isChoiceTypePath('Observation.value')  // false
+ */
+export declare function isChoiceTypePath(path: string): boolean;
+/**
+ * Check whether `concretePath` matches a choice type `choicePath`.
+ *
+ * The concrete path must share the same prefix (minus `[x]`) and the
+ * remaining suffix must start with an uppercase letter (the type name).
+ *
+ * @example
+ * matchesChoiceType('Observation.value[x]', 'Observation.valueString')    // true
+ * matchesChoiceType('Observation.value[x]', 'Observation.valueQuantity')  // true
+ * matchesChoiceType('Observation.value[x]', 'Observation.code')           // false
+ * matchesChoiceType('Observation.value[x]', 'Observation.value')          // false
+ */
+export declare function matchesChoiceType(choicePath: string, concretePath: string): boolean;
+/**
+ * Extract the type name from a concrete choice path given the choice base.
+ *
+ * @example
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.valueString')    // 'String'
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.valueQuantity')  // 'Quantity'
+ * extractChoiceTypeName('Observation.value[x]', 'Observation.code')           // undefined
+ */
+export declare function extractChoiceTypeName(choicePath: string, concretePath: string): string | undefined;
+/**
+ * Check whether an element id contains a slice name (`:` separator).
+ *
+ * In FHIR, slice names appear in element ids, not in paths.
+ * Format: `"ResourceType.path:sliceName"` or `"ResourceType.path:sliceName.child"`
+ *
+ * @example
+ * hasSliceName('Patient.identifier:MRN')            // true
+ * hasSliceName('Patient.identifier:MRN.system')     // true
+ * hasSliceName('Patient.identifier')                // false
+ */
+export declare function hasSliceName(elementId: string): boolean;
+/**
+ * Extract the first slice name from an element id.
+ *
+ * @example
+ * extractSliceName('Patient.identifier:MRN')         // 'MRN'
+ * extractSliceName('Patient.identifier:MRN.system')   // 'MRN'
+ * extractSliceName('Patient.identifier')              // undefined
+ */
+export declare function extractSliceName(elementId: string): string | undefined;
+/**
+ * Compute the child element scope for a parent element in a list.
+ *
+ * Returns a {@link TraversalScope} covering all direct and indirect
+ * children of the element at `parentIndex`. Both `start` and `end`
+ * are inclusive indices.
+ *
+ * Returns `undefined` if the parent has no children.
+ *
+ * @example
+ * // elements: [Patient, Patient.id, Patient.name, Patient.name.given,
+ * //            Patient.name.family, Patient.identifier]
+ * getChildScope(elements, 2)
+ * // → { elements, start: 3, end: 4 }  (Patient.name.given, Patient.name.family)
+ */
+export declare function getChildScope(elements: readonly ElementDefinition[], parentIndex: number): TraversalScope | undefined;
+/**
+ * Find differential elements matching `basePath` within the given scope.
+ *
+ * Matching rules (mirrors HAPI `getDiffMatches`):
+ * 1. Exact path match
+ * 2. Choice type match (base ends with `[x]`, diff has concrete type)
+ * 3. Same path with different sliceName (slice match)
+ *
+ * Only considers unconsumed trackers within `[diffStart, diffEnd]` inclusive.
+ */
+export declare function getDiffMatches(differential: readonly DiffElementTracker[], basePath: string, diffStart: number, diffEnd: number): DiffElementTracker[];
+/**
+ * Check whether the differential contains descendant elements of `basePath`
+ * within the given scope.
+ *
+ * This corresponds to HAPI's `hasInnerDiffMatches()` — it detects whether
+ * the diff constrains children of an element even when the element itself
+ * has no direct diff match.
+ */
+export declare function hasInnerDiffMatches(differential: readonly DiffElementTracker[], basePath: string, diffStart: number, diffEnd: number): boolean;
+/**
+ * Rewrite a path from one prefix to another.
+ *
+ * Used during datatype expansion: when diving into a complex type's
+ * snapshot, paths need to be rewritten from the datatype's namespace
+ * to the target element's namespace.
+ *
+ * @example
+ * rewritePath('Identifier.system', 'Identifier', 'Patient.identifier')
+ * // → 'Patient.identifier.system'
+ *
+ * rewritePath('Identifier', 'Identifier', 'Patient.identifier')
+ * // → 'Patient.identifier'
+ *
+ * rewritePath('HumanName.given', 'HumanName', 'Patient.name')
+ * // → 'Patient.name.given'
+ */
+export declare function rewritePath(sourcePath: string, sourcePrefix: string, targetPrefix: string): string;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/lib/profile/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/profile/path-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMrE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAM5E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAMD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAOnF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,SAAS,CAIpB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOtE;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,MAAM,GAClB,cAAc,GAAG,SAAS,CAuB5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAuBtB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CA8BT;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CASR"}

package/dist/lib/profile/slicing-handler.d.ts

@@ -0,0 +1,121 @@
+/**
+ * fhir-profile — Slicing Handler
+ *
+ * Dedicated module for FHIR slicing operations during snapshot generation.
+ * Corresponds to the slicing branches in HAPI FHIR R4's `processPaths()`.
+ *
+ * Slicing is the **second most complex** part of snapshot generation
+ * (after `processPaths` itself). This module extracts slicing logic into
+ * well-tested, independently callable functions.
+ *
+ * Two primary scenarios:
+ * - **Case A (handleNewSlicing)**: Base is unsliced, differential introduces slicing
+ * - **Case B (handleExistingSlicing)**: Base is already sliced, differential modifies/extends
+ *
+ * Supporting functions:
+ * - {@link getSliceSiblings} — collect base slice siblings
+ * - {@link validateSlicingCompatibility} — check diff slicing vs base slicing
+ * - {@link diffsConstrainTypes} — detect type slicing pattern
+ * - {@link makeExtensionSlicing} — synthesize default extension slicing
+ *
+ * @module fhir-profile
+ */
+import type { ElementDefinition, ElementDefinitionSlicing, ElementDefinitionType } from '../model/index.js';
+import type { DiffElementTracker, SnapshotIssue, TraversalScope } from './types.js';
+import type { MergeContext } from './element-merger.js';
+/**
+ * Generate the default slicing definition for extension elements.
+ *
+ * Corresponds to HAPI's `makeExtensionSlicing()`. Extension elements
+ * are always sliced by `url` using the `value` discriminator type.
+ *
+ * @returns A new {@link ElementDefinitionSlicing} for extensions.
+ */
+export declare function makeExtensionSlicing(): ElementDefinitionSlicing;
+/**
+ * Get all sibling slices from a base snapshot starting after the slicing root.
+ *
+ * Corresponds to HAPI's `getSiblings()`. Collects all elements with the
+ * same path as the slicing root that have a `sliceName`, plus their children.
+ *
+ * @param elements - The base snapshot element list.
+ * @param slicingRootIndex - Index of the slicing root element.
+ * @returns Array of slice elements (each with sliceName) and their children.
+ */
+export declare function getSliceSiblings(elements: readonly ElementDefinition[], slicingRootIndex: number): ElementDefinition[];
+/**
+ * Validate that a differential slicing definition is compatible with
+ * the base slicing definition.
+ *
+ * Rules:
+ * - Discriminators must match (same type and path, in same order)
+ * - `ordered` cannot change from `true` to `false`
+ * - `rules` cannot relax from `closed` to `open`/`openAtEnd`
+ *
+ * @param baseSlicing - The base element's slicing definition.
+ * @param diffSlicing - The differential element's slicing definition.
+ * @param issues - Issue collector for recording incompatibilities.
+ * @param path - Element path for issue reporting.
+ * @returns `true` if compatible, `false` if incompatible.
+ */
+export declare function validateSlicingCompatibility(baseSlicing: ElementDefinitionSlicing, diffSlicing: ElementDefinitionSlicing, issues: SnapshotIssue[], path: string): boolean;
+/**
+ * Detect whether diff matches constitute type slicing.
+ *
+ * Corresponds to HAPI's `diffsConstrainTypes()`. Type slicing is detected when:
+ * - Multiple diff matches exist
+ * - All diff matches constrain different types, OR
+ * - The base is a choice type `[x]` and diffs use concrete type paths
+ *
+ * @param diffMatches - The differential element trackers that matched a base path.
+ * @param basePath - The base element path.
+ * @param baseTypes - The base element's type list (optional).
+ * @returns `true` if the diffs represent type slicing.
+ */
+export declare function diffsConstrainTypes(diffMatches: readonly DiffElementTracker[], basePath: string, baseTypes: readonly ElementDefinitionType[] | undefined): boolean;
+/**
+ * Handle Case A: Base is unsliced, differential introduces slicing.
+ *
+ * Steps:
+ * 1. Create slicing root element (from diff slicing definition or synthesized extension slicing)
+ * 2. Add slicing root to result
+ * 3. For each diff slice, recursively process against the same base range
+ *
+ * @param context - Shared merge state.
+ * @param result - Mutable output array.
+ * @param currentBase - The base element being sliced.
+ * @param baseScope - Scope of the base element and its children.
+ * @param diffMatches - Diff trackers that matched this base path.
+ * @param diffTrackers - All diff trackers (for recursive calls).
+ * @param diffStart - Start index in diffTrackers.
+ * @param diffEnd - End index in diffTrackers.
+ * @param contextPathSrc - Source path prefix for rewriting.
+ * @param contextPathDst - Destination path prefix for rewriting.
+ * @param cpath - The current (rewritten) path.
+ */
+export declare function handleNewSlicing(context: MergeContext, result: ElementDefinition[], currentBase: ElementDefinition, baseScope: TraversalScope, diffMatches: DiffElementTracker[], diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string, cpath: string): void;
+/**
+ * Handle Case B: Base is already sliced, differential modifies/extends slices.
+ *
+ * Steps:
+ * 1. Copy base slicing root (merge diff slicing definition if present)
+ * 2. Collect base slice siblings
+ * 3. Align base slices with diff slices by sliceName
+ * 4. Matched slices → merge constraints
+ * 5. Unmatched base slices → copy as-is
+ * 6. Remaining diff slices → append as new (only if open/openAtEnd)
+ *
+ * @param context - Shared merge state.
+ * @param result - Mutable output array.
+ * @param currentBase - The base slicing root element.
+ * @param baseScope - Scope of the base element and its children.
+ * @param diffMatches - Diff trackers that matched this base path.
+ * @param diffTrackers - All diff trackers (for recursive calls).
+ * @param diffStart - Start index in diffTrackers.
+ * @param diffEnd - End index in diffTrackers.
+ * @param contextPathSrc - Source path prefix for rewriting.
+ * @param contextPathDst - Destination path prefix for rewriting.
+ * @param cpath - The current (rewritten) path.
+ */
+export declare function handleExistingSlicing(context: MergeContext, result: ElementDefinition[], currentBase: ElementDefinition, baseScope: TraversalScope, diffMatches: DiffElementTracker[], diffTrackers: readonly DiffElementTracker[], diffStart: number, diffEnd: number, contextPathSrc: string, contextPathDst: string, cpath: string): void;
+//# sourceMappingURL=slicing-handler.d.ts.map