feat: FHIRPath 3.0.0 functions, instance selectors, and pathname()

[fjsj]

This PR implements the seven FHIRPath 3.0.0 issues (spec). Each behavior follows the 3.0.0 text and its examples, and every spec example is a test.

Builds on #110 (merged): the repeat() limit, scalar-value string functions, the Date + hour error, and EqualityIndex. None of #110's behavior changes here; main is merged in with its last two commits.

Closes #111, closes #112, closes #113, closes #114, closes #115, closes #116, closes #117.

Changes

Issue	Change
#111	matches(), matchesFull(), and replaceMatches() take an optional flags argument: i ignores case and m makes ^/$ match at line breaks. Other flags throw, and the analyzer reports a literal one (invalid-argument). The runtime and analyzer share one rule. The matches-flags-argument quirk family is removed, and its 10 fhirpath.js cases now pass. A custom EvaluateOptions.regex engine receives i/m.
#112	repeatAll() keeps duplicates. It shares MAX_REPEAT_ITEMS (10,000) with repeat(), so the spec's unsafe examples ('abc'.repeatAll(replace('a', 'A')), Questionnaire.repeatAll('item')) throw. The analyzer signature matches repeat()'s (unordered).
#113	duration() and difference() follow the spec's precision table. Weeks start on Sunday. Timezone offsets are normalized for hour and smaller precisions. The result is empty when an operand is less precise than the requested precision. A precision the operand types don't allow throws, and the analyzer reports a literal one.
#114	toDate(), toDateTime(), convertsToDate(), and convertsToDateTime() take a format for a String input. All the spec's required codes are supported, plus yy, M, d, h, H, m, s, MMM, and MMMM (English). Other inputs ignore the format. The analyzer reports a literal format that can't compile.
#115	pathname([short]) (forked work, reviewed). Navigation records an item's origin (parent, element, JSON index) only when the evaluation can reach a pathname() call. That includes vars, expression-function bodies, DTO columns, and instance-selector values. The benchmark shows no measurable cost with tracking on or off. Paths cover children(), descendants(), and extension(), plus resolve() into contained resources and Bundle entries. A new "Element paths" section in docs/api.md describes them.
#116	Instance selectors (forked work, reviewed). The change touches the lexer (: token), parser, AST, printer, evaluator, analyzer, and type-level parser. With a model, unknown types, unknown elements, wrong value types, and several values for a non-repeating element are errors at runtime and in the analyzer, through one shared rule. A choice element takes its key from the value's type (Observation { value: 5 'mg' } sets valueQuantity). Type inference gives a selector unknown[] and keeps the surrounding expression typed: the generated interfaces list required-binding codes that the runtime doesn't check in a built value (#133).
#117	combine(other, preserveOrder) and encode('ascii'). combine() keeps its sources' order whatever preserveOrder says. ascii gives one ? per Unicode scalar value above 127, so an emoji is one ?. decode('ascii') stays unsupported, as in the spec.

Decisions for review

• combine(), union(), and | keep their sources' order, a deliberate spec deviation. The spec says "when preserveOrder is false, or not supplied, there is no expectation of order", and gives union() no order. The runtime appends in order, and the analyzer treats all three results as ordered, so x.combine(y).first() and (a | b).first() are not order-dependent errors. A new "Deviations from the specification" section in docs/conformance.md records this, and docs/static-checking.md links to it.
• repeatAll() outputs only projected items, not the input, as repeat() does. fhirpath-rs testRepeatAllFiniteSequence expects 10.repeatAll(iif($this > 1, $this - 2, {})).count() = 6; this engine gives 5 (8, 6, 4, 2, 0). fhirpath-rs testRepeatAllBasic expects Patient.name.repeatAll('test') to succeed, but the spec lists that form as one that never terminates, and here it hits the limit.
• duration()/difference() details the spec leaves open:
  • Only singular precision words are accepted ('years' throws), matching the spec's list.
  • A Date measured against a DateTime counts as a DateTime.
  • Components below the less precise operand are ignored.
  • At hour and smaller precisions, a DateTime with an offset against one without gives empty, as comparison does.
• Date formats:
  • Two-digit years use the spec's suggested pivot: 00–49 is 20xx, 50–99 is 19xx, which matches the spec's '12-27'.toDate('MM-yy') → @2027-12.
  • The time zone name code z reads an IANA id in Area/Location form, or UTC/GMT, and takes the zone's offset at that date and time through Intl.DateTimeFormat. Abbreviations (PST) and names (Pacific Standard Time) don't match, even where ICU accepts them. A wall time a DST change repeats takes the earlier instant, as Temporal's compatible disambiguation does. A skipped wall time, or an offset that isn't whole minutes (local mean time, such as New York in 1850), gives empty.
  • A format with no year, a gap (a day without a month), h without a, or a zone code without an hour throws.
  • Month names and AM/PM markers are read in English, case-insensitive. Literal characters match exactly.
• matchesFull() with m matches when any one line matches whole (^(?:pattern)$ with multi-line ^/$), as fhirpath.js expects. The extended R5 suite in reason-healthcare/rh expects the whole value instead; the spec's "completely matches" and its m definition pull both ways.
• Instance selector input: an empty focus gives empty, as the spec says. So r4.evaluate("Coding { code: 'x' }") with no input returns []. The model has no minimum cardinalities, so a selector that omits a required element (e.g. Observation {:}) is not reported; Instance selectors: report missing required elements #124 tracks that. %factory stays deferred in the README.
• Instance selector values match FHIR's primitive patterns. Each primitive a selector writes must match its type's regex from the R4 definitions, generated into src/r4/generated/primitive-patterns.ts and served by a new optional ModelProvider.valuePattern(). So unsignedInt { value: -1 }, Coding { code: ' a' }, HumanName { family: '' }, and Observation { effective: @2020-01-01T10:00 } (a time without seconds and a time zone) throw a FhirPathRuntimeError, and the static checkers report a literal one (invalid-value). Values read from data are checked too. The message names the element, type, and pattern, never the value, which may be patient data. The generator rewrites two things for a JS RegExp, and fails if a source pattern changes or a bare \s remains:
  • \s/\S use Java's whitespace set, the dialect of HAPI's validator. A JS \s also matches U+00A0 and U+3000, so a valid name such as Yamada　Taro would fail string.
  • FHIR's own base64Binary pattern backtracks exponentially in a JS RegExp (a 120-character invalid value took over a minute), so it gets an equivalent that matches in linear time; a test checks every pattern stays linear.
• Instance selector gap: backbone elements can't be built yet; fhirpath.js accepts BackboneElement { ... } there (Instance selectors: build backbone elements with BackboneElement { ... } #132).
• pathname() roots:
  • A root with a resourceType starts the path with that type, with no indexer.
  • A root without one gives relative paths (given[0]), and the root itself gives no path.
  • resolve('#') now returns the root item itself.
• Type-level cost: the API surface is +4.7% over its baseline and the full language +4.3% (limit 5%), up from +3.6% on Fix six behaviors found by the upstream test audit #110. The extra comes from four new function names in the generated unions and the selector tokenizer rule. A first parser-branch version of the selector rule reached +5.4%, so detection moved into the tokenizer (recorded in AGENTS.md). The budget is not raised.
• Corpus gaps: no reference suite calls difference, duration, pathname, or repeatAll yet. corpus-audit.test.ts lists them next to convertsToLong; their unit tests and the generated function capabilities cover them.

Upstream validation

The official suites (FHIR/fhir-test-cases R4, R4B, R5, R6) have no 3.0.0 cases, and the HL7/FHIRPath repo hasn't changed these sections since 3.0.0. So every 3.0.0 case I could find in other engines' tests was run against this branch:

Source	3.0.0 cases	Result
#110's audit (fhirpath.js, fhirpath-py, fhirpath-rs, Helios, HL7 Java core, Medplum, kotlin, HAPI)	37	34 pass; 3 are the fhirpath-rs repeatAll() differences above
Josh Mandel's fhirpath.zig and fhirpath.wasm tests	29	all pass
Extended R5 suite in reason-healthcare/rh	58	54 pass; the other 4 contradict the spec or their fixture, or are the matchesFull() question above
gofhir, Pathling, Ignixa, fhirpath.js pathname/selector tests	~280	pass except engine design differences and tests the 3.0.0 text contradicts

The cases the suite lacked are now in it: src/reference-crosschecks.test.ts (fhirpath-rs, Helios, fhirpath.zig) and test-data/crosschecks/fhirpath-3.0.0.json (179 cases from gofhir, Pathling, Ignixa, and fhirpath.js).

Then every evaluation the test suite makes for these features went through the analyzer the way strict evaluation runs it, comparing diagnostics and result types with the runtime. Together the two passes found these bugs, all fixed here:

• combine()'s preserveOrder and pathname()'s short accepted any value as true; a non-Boolean now throws, as the analyzer already reported.
• Element names on Object.prototype (Patient.constructor, Coding { constructor: 'x' }) crashed the runtime and the analyzer with a JS TypeError. This predates the PR, in the R4 model's element lookup; unescape('html') had the same problem with &constructor; (Fix six behaviors found by the upstream test audit #110).
• unsignedInt { value: 5 } and positiveInt { value: 1 } were rejected, because the R4 model types their value as System.String.
• duration() returned -0 for less than one period backwards.
• The analyzer missed a Time measured against a Date, unsupported literal encode()/decode() formats and escape()/unescape() targets, and typed 2147483648 as Integer where the runtime gives a Long.
• The analyzer read a repeat()/repeatAll() projection against the first round only, so QuestionnaireResponse.repeat(item | answer.item) was an unknown-element error. It now types $this over every round.

The remaining differences are the analyzer's usual strictness (unknown elements, wrong input types, and possibly-many values that the runtime turns into empty or tolerates), plus misses it can't see: an untyped env value, and gender.repeatAll(length()), whose first round is valid. Follow-ups found on the way, outside this PR: #127 (sort() asc/desc), #128 (min()/max() on dates and strings), #129 (ignored escapes), #130 (as(Quantity) drops Age), #131 (= and element ids), #132 (BackboneElement selectors).

Review loop

An independent review pass (Opus, read-only) found two blockers, both fixed: selector types claimed codes the runtime never checks (now unknown[], #133 for the code checks), and the patterns' JS \s rejected valid Unicode-spaced strings (now Java's whitespace). It also led to one shared loop for repeat()/repeatAll(), one systemTypeOfName() helper in place of three copies, and four text fixes. The second pass approved.

Validation

• pnpm typecheck, lint, test (8,649 passed, 1,446 skipped), check:fhirpath, check:inference (2,116 precise, 0 conflicts), check:type-perf, coverage (statements 99.43%, branches 96.97%), build, and check:package (TypeScript 5.9.3 and 5.4.5) all pass.
• The fhirpath.js corpus is now 2,306 passing and 1,363 skipped, with 236 quirk entries. docs/conformance.md has the new counts, which also include Fix six behaviors found by the upstream test audit #110's changes.
• The demo has no AST switches. Its Monaco declarations are generated at build time and gitignored. I did not run the demo's own typecheck, because its dependencies aren't installed here.

🤖 Generated with Claude Code