fhirpath-ts 0.0.0-bootstrap.0

package/src/cli/dto-check.ts

@@ -0,0 +1,94 @@
+/**
+ * Imports DTO modules, records the engines they create, and checks each exported
+ * DTO with loaded runtime context. The default module pattern is `*.dto.ts`.
+ * Importing runs module initialization; `--no-import` skips this pass.
+ */
+/* v8 ignore file -- covered end-to-end as a subprocess in fhirpath-check.test.ts, which is the only way to exercise a module loader and engine discovery in a fresh process */
+import { glob } from 'node:fs/promises'
+import { register } from 'node:module'
+import { relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { type AnalyzedContext, analyzeDto, type DtoDiagnostic } from '../analyzer/analyze-dto.ts'
+import { type DtoClass, isDtoClass } from '../api/dto.ts'
+import { type FhirPathEngine, recordEngines } from '../api/engine.ts'
+
+/** Where DTO classes live unless `--dtos` says otherwise. */
+export const DEFAULT_DTO_GLOB = '**/*.dto.ts'
+
+const IGNORED = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**']
+
+/** One finding, with the DTO and file it belongs to and the expression that produced it. */
+export interface DtoFinding extends DtoDiagnostic {
+  /** The DTO class name. */
+  dto: string
+  /** The module the DTO was imported from, relative to the working directory. */
+  file: string
+}
+
+export interface DtoCheckResult {
+  findings: DtoFinding[]
+  /** Modules that matched and were imported, relative to the working directory. */
+  files: string[]
+  /** How many engines the imported modules constructed. */
+  engines: number
+  /** Every DTO analyzed, by module. */
+  dtos: { file: string; dto: string }[]
+}
+
+/** Imports matching modules and checks their exported DTOs against recorded engines. */
+export async function checkDtoModules(patterns: readonly string[], cwd: string): Promise<DtoCheckResult> {
+  const recorded = recordEngines()
+  register(new URL('ts-loader.mjs', import.meta.url))
+  const files: string[] = []
+  const dtos: { file: string; dto: string; cls: DtoClass }[] = []
+  for await (const match of glob(patterns.length > 0 ? [...patterns] : [DEFAULT_DTO_GLOB], { cwd, exclude: IGNORED })) {
+    const file = relative(cwd, new URL(match, pathToFileURL(`${cwd}/`)).pathname)
+    files.push(file)
+    const module: Record<string, unknown> = await import(pathToFileURL(`${cwd}/${match}`).href)
+    for (const [name, value] of Object.entries(module)) {
+      if (isDtoClass(value)) {
+        dtos.push({ file, dto: value.name || name, cls: value })
+      }
+    }
+  }
+  const engines = recorded()
+  const findings = dtos.flatMap(({ file, dto, cls }) =>
+    analyzeFor(cls, engines).map(finding => ({ ...finding, dto, file }))
+  )
+  return { findings, files, engines: engines.length, dtos: dtos.map(({ file, dto }) => ({ file, dto })) }
+}
+
+/**
+ * A DTO against the engine that registered it, or — when no engine claims it, as
+ * for a row shape that is only ever projected — against everything the project's
+ * engines make available. A DTO checked against one engine of several would
+ * report calls that resolve perfectly well in the engine it actually runs on, and
+ * "some engine in this project declares this" is the most that can be said
+ * without being told which. Merging says exactly that, once, in engine order.
+ */
+function analyzeFor(dto: DtoClass, engines: readonly FhirPathEngine[]): DtoDiagnostic[] {
+  const owner = engines.find(engine => engine.dtos.includes(dto))
+  if (owner !== undefined) {
+    return analyzeDto(dto, { engine: owner })
+  }
+  if (engines.length === 0) {
+    return analyzeDto(dto)
+  }
+  return analyzeDto(dto, { engine: merged(engines) })
+}
+
+/**
+ * Every engine's context as one: the union of their registered functions and env
+ * names. The first engine's `model` stands for all of them — a project binds one
+ * FHIR version, and an unregistered DTO names no engine that could pick another.
+ */
+function merged(engines: readonly FhirPathEngine[]): AnalyzedContext {
+  return {
+    defaults: {
+      ...engines[0]?.defaults,
+      functions: Object.assign({}, ...engines.map(engine => engine.defaults.functions)),
+      env: Object.assign({}, ...engines.map(engine => engine.defaults.env)),
+    },
+  }
+}

package/src/cli/fhirpath-check.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Checks source literals with the TypeScript site finder, then imports DTO
+ * modules for checks that need their engine context. Errors produce a non-zero
+ * exit status. Use `--no-import` for source only and `--dtos` to change the DTO
+ * module glob.
+ *
+ * Usage: fhirpath-check [--dtos <glob>]... [--no-import] <file...>
+ */
+/* v8 ignore file -- covered end-to-end as a subprocess in fhirpath-check.test.ts */
+import { readFileSync } from 'node:fs'
+
+import ts from 'typescript'
+
+import { analyzeSite } from '../analyzer/analyze.ts'
+import { r4Model } from '../r4/index.ts'
+import { createSiteFinder, type ExpressionSite } from '../sites/index.ts'
+import { checkDtoModules, DEFAULT_DTO_GLOB, type DtoFinding } from './dto-check.ts'
+
+const findExpressionSites = createSiteFinder(ts)
+
+interface Args {
+  files: string[]
+  dtoGlobs: string[]
+  imports: boolean
+}
+
+function parseArgs(argv: readonly string[]): Args {
+  const args: Args = { files: [], dtoGlobs: [], imports: true }
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]!
+    if (arg === '--no-import') {
+      args.imports = false
+    } else if (arg === '--dtos') {
+      const glob = argv[++index]
+      if (glob === undefined) {
+        console.error('fhirpath-check: --dtos needs a glob')
+        process.exit(2)
+      }
+      args.dtoGlobs.push(glob)
+    } else {
+      args.files.push(arg)
+    }
+  }
+  return args
+}
+
+const args = parseArgs(process.argv.slice(2))
+if (args.files.length === 0 && !args.imports) {
+  console.error('usage: fhirpath-check [--dtos <glob>]... [--no-import] <file...>')
+  process.exit(2)
+}
+
+let failures = 0
+
+function report(location: string, diagnostic: { severity: string; code: string; message: string }): void {
+  if (diagnostic.severity === 'error') {
+    failures += 1
+  }
+  const prefix = diagnostic.severity === 'warning' ? 'warning:' : ''
+  console.error(`${location} [${prefix}${diagnostic.code}] ${diagnostic.message}`)
+}
+
+/**
+ * Where a diagnostic falls in the file, given the site its expression came from.
+ * A span's own line/column are relative to the expression text, so only a
+ * first-line column is an offset from the site's; a later line starts at its own
+ * column 1.
+ */
+function positionIn(site: { line: number; column: number }, span: { line: number; column: number }): string {
+  const line = site.line + (span.line - 1)
+  const column = span.line === 1 ? site.column + span.column - 1 : span.column
+  return `${line}:${column}`
+}
+
+/** Expression sites cached so each source file is read once. */
+const sitesByFile = new Map<string, ExpressionSite[]>()
+
+function sitesOf(file: string): ExpressionSite[] {
+  const cached = sitesByFile.get(file)
+  if (cached !== undefined) {
+    return cached
+  }
+  const sites = findExpressionSites(readFileSync(file, 'utf8'), file)
+  sitesByFile.set(file, sites)
+  return sites
+}
+
+// Check source literals first.
+for (const file of args.files) {
+  let sites: ExpressionSite[]
+  try {
+    sites = sitesOf(file)
+  } catch (error) {
+    console.error(`fhirpath-check: cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`)
+    process.exit(2)
+  }
+  for (const site of sites) {
+    for (const diagnostic of analyzeSite(site, { model: r4Model })) {
+      report(`${file}:${positionIn(site, diagnostic.span)}`, diagnostic)
+    }
+  }
+}
+
+/**
+ * A DTO finding's position in source: `analyzeDto` knows the member and the
+ * expression, and the site finder knows where each expression literal sits, so
+ * the expression text joins the two. Identical expressions in one file share the
+ * first match — a cosmetic tie, not a wrong finding. A file that cannot be read,
+ * or an expression with no literal to point at (one built at runtime), degrades
+ * to naming the member.
+ */
+function locate(finding: DtoFinding): string {
+  const member = `${finding.dto}.${finding.member}`
+  let site: ExpressionSite | undefined
+  try {
+    site = sitesOf(finding.file).find(candidate => candidate.expression === finding.expression)
+  } catch {
+    return `${finding.file} ${member}`
+  }
+  return site === undefined
+    ? `${finding.file} ${member}`
+    : `${finding.file}:${positionIn(site, finding.span)} ${member}`
+}
+
+// --- 2. the project's DTO modules, imported ---
+if (args.imports) {
+  const globs = args.dtoGlobs.length > 0 ? args.dtoGlobs : [DEFAULT_DTO_GLOB]
+  let result
+  try {
+    result = await checkDtoModules(globs, process.cwd())
+  } catch (error) {
+    console.error(
+      `fhirpath-check: cannot import DTO modules (${globs.join(', ')}): ${error instanceof Error ? error.message : String(error)}`
+    )
+    process.exit(2)
+  }
+  for (const finding of result.findings) {
+    // With no engine in reach, an unresolved column call is unresolvable rather
+    // than wrong, so it is reported without failing the run.
+    const unresolvable = result.engines === 0 && finding.code === 'unknown-function'
+    report(locate(finding), unresolvable ? { ...finding, severity: 'warning' } : finding)
+  }
+  if (result.files.length === 0) {
+    console.error(
+      `fhirpath-check: no DTO modules matched ${globs.join(', ')} — DTOs live in *.dto.ts, or pass --dtos <glob>`
+    )
+  } else if (result.dtos.length === 0) {
+    console.error(`fhirpath-check: ${result.files.length} DTO module(s) matched but export no DTO class`)
+  } else if (result.engines === 0) {
+    // Without an engine, a call into another DTO's column cannot resolve, so the
+    // DTO half would report valid code. Say so instead of failing the run.
+    console.error(
+      'fhirpath-check: no engine was constructed by the imported modules — column function calls cannot be resolved; ' +
+        'point --dtos at the module that builds your FhirPathEngine'
+    )
+  } else {
+    console.log(
+      `fhirpath-check: analyzed ${result.dtos.length} DTO(s) from ${result.files.length} module(s) against ${result.engines} engine(s)`
+    )
+  }
+}
+
+if (failures > 0) {
+  console.error(`fhirpath-check: ${failures} problem(s) found`)
+  process.exit(1)
+}
+console.log('fhirpath-check: no problems found')

package/src/cli/ts-loader.mjs

@@ -0,0 +1,49 @@
+/**
+ * Minimal Node loader for DTO checks. It compiles standard decorators to ES2022
+ * before importing TypeScript modules. It does not read tsconfig paths or run
+ * type checks; projects that need custom module resolution should compile first.
+ */
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import ts from 'typescript'
+
+const COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  useDefineForClassFields: true,
+  experimentalDecorators: false,
+  inlineSourceMap: true,
+  inlineSources: true,
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  try {
+    return await nextResolve(specifier, context)
+  } catch (error) {
+    // A relative import written without an extension: try the TypeScript file
+    // the project meant, then its directory index.
+    if (specifier.startsWith('.') && !/\.[cm]?[jt]sx?$/.test(specifier)) {
+      for (const candidate of [`${specifier}.ts`, `${specifier}/index.ts`]) {
+        try {
+          return await nextResolve(candidate, context)
+        } catch {
+          continue
+        }
+      }
+    }
+    throw error
+  }
+}
+
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith('file:') || !/\.[cm]?ts$/.test(url)) {
+    return nextLoad(url, context)
+  }
+  const fileName = fileURLToPath(url)
+  const { outputText } = ts.transpileModule(await readFile(fileName, 'utf8'), {
+    fileName,
+    compilerOptions: COMPILER_OPTIONS,
+  })
+  return { format: 'module', shortCircuit: true, source: outputText }
+}

package/src/engine/context.ts

@@ -0,0 +1,282 @@
+import { FhirPathTypeError } from '../errors.ts'
+import { functions as builtinFunctions } from '../functions/registry.ts'
+import type { ModelProvider } from '../model/provider.ts'
+import type { AstNode } from '../parser/ast.ts'
+import { SYSTEM_STRING, toCollection, type TypedValue } from '../values/typed-value.ts'
+
+/**
+ * The runtime side of a native host-supplied function: arity and implementation.
+ * The API layer's CustomFunction (api/compile.ts) adds the optional analyzer
+ * signature; this module only needs what evaluation uses.
+ */
+export interface HostNativeFunction {
+  /** Inclusive argument count range, checked before invocation. Defaults: 0 to unlimited. */
+  minArity?: number
+  maxArity?: number
+  /**
+   * Model type names the call's focus must be able to hold, spelled as the
+   * caller wrote them. Either a local name or a canonical one works, because
+   * `unsatisfiedInput` (values/type-compat.ts) canonicalizes the names it
+   * compares. Leave this out to accept any focus, which is what every function
+   * that does not declare `signature.input.types` does.
+   */
+  inputTypes?: readonly string[]
+  /**
+   * The implementation. `input` is the unwrapped input collection; each
+   * argument is eagerly evaluated against `$this` — the enclosing context
+   * item, like built-in value arguments — and arrives as an unwrapped
+   * collection. Return a plain value, an array of plain values, or undefined
+   * for empty — the engine converts back to its typed representation.
+   */
+  fn: (input: unknown[], ...args: unknown[][]) => unknown
+}
+
+/**
+ * The runtime side of an expression-defined function (CustomFunction's
+ * `expression` form, pre-parsed by the API layer). Zero arguments; the body
+ * evaluates as if spliced at the call site, with the call's input as focus.
+ */
+export interface HostExpressionFunction {
+  ast: AstNode
+  /** See HostNativeFunction.inputTypes. Same meaning, checked the same way. */
+  inputTypes?: readonly string[]
+  /**
+   * Environment variables the body reads that the caller does not supply, laid
+   * over the caller's env for the length of the call and gone again after it
+   * (see `withEnvOverlay`). This is how a DTO's `env` reaches its own column
+   * bodies without being published to every expression the engine evaluates.
+   * Already in collection form, since the same overlay serves every call.
+   */
+  env?: ReadonlyMap<string, TypedValue[]>
+  /**
+   * Apply the criteria rule to the body's result, so the function always returns
+   * exactly one Boolean. That rule is `criteriaBoolean`: §4.5 singleton
+   * evaluation, with an empty result read as false. It is what makes a
+   * `@criteria` mean the same thing whether it is projected as a column or
+   * called from an expression.
+   */
+  criteria?: boolean
+}
+
+/** One host-supplied function, in either form. */
+export type HostSingleFunction = HostNativeFunction | HostExpressionFunction
+
+/**
+ * Several functions registered under one name, told apart by the focus each was
+ * written for. A call runs the first whose `inputTypes` the focus satisfies (see
+ * `resolveHostCall`), so two DTOs may both declare a `displayText` column as
+ * long as a CodeableConcept can never be a Coding. Every member must declare
+ * `inputTypes` for that to mean anything, which is what `withDtos` (api/dto.ts)
+ * checks before it builds one.
+ */
+export interface HostOverloadedFunction {
+  overloads: readonly HostSingleFunction[]
+}
+
+export type HostFunction = HostSingleFunction | HostOverloadedFunction
+
+/**
+ * A pluggable regular-expression engine for matches()/matchesFull()/
+ * replaceMatches(). The default is the built-in RegExp, which backtracks and
+ * cannot be timed out synchronously — hosts evaluating untrusted expressions
+ * can supply a linear-time engine (e.g. an RE2 binding) here instead.
+ */
+export interface RegexEngine {
+  /**
+   * Compile `pattern` with `flags` (a subset of 's' and 'g'; matchesFull
+   * wraps the pattern in `^(?:...)$` before compiling). Throw on invalid
+   * patterns — the engine converts that to the spec's type error.
+   */
+  compile(
+    pattern: string,
+    flags: string
+  ): {
+    test(subject: string): boolean
+    /** Replace every match (the 'g' flag is passed for replaceMatches). */
+    replace(subject: string, substitution: string): string
+  }
+}
+
+/** `$this` / `$index` / `$total` bindings; iteration functions push one frame per element. */
+export interface Frame {
+  parent: Frame | undefined
+  thisValue: TypedValue[]
+  index: number | undefined
+  total: TypedValue[] | undefined
+}
+
+export interface EvaluationContext {
+  /** The original input node: `%context`. */
+  root: TypedValue[]
+  /** Environment variables by name (without the `%`). Values are collections. */
+  env: ReadonlyMap<string, TypedValue[]>
+  model: ModelProvider | undefined
+  /** Fixed evaluation clock so now()/today()/timeOfDay() are stable within one evaluation. */
+  now: Date
+  /**
+   * Sink for trace(). Default is a no-op: traced values may contain patient data,
+   * so writing them to console or log files is the caller's deliberate choice.
+   */
+  trace: (name: string, values: TypedValue[]) => void
+  /**
+   * Variables from defineVariable(), seeded with the call's `vars` bindings.
+   * The map is local to one expression chain: dots thread it along, while
+   * operator operands, function arguments, and iteration frames evaluate
+   * against a copy (see forkVariables).
+   */
+  variables: Map<string, TypedValue[]>
+  /** Host-supplied functions by name; never contains a built-in name (createContext rejects overrides). */
+  functions: ReadonlyMap<string, HostFunction>
+  /**
+   * Names of expression-defined functions currently on the call stack. One
+   * shared Set per evaluation (context copies keep the reference), so a
+   * definition that reaches itself — directly or through another definition —
+   * fails as recursion instead of overflowing the stack.
+   */
+  activeExpressionFunctions: Set<string>
+  /** Regex engine for the matches() family; undefined means the built-in RegExp. */
+  regex: RegexEngine | undefined
+  frame: Frame
+}
+
+const BUILTIN_CONSTANTS: ReadonlyMap<string, string> = new Map([
+  ['ucum', 'http://unitsofmeasure.org'],
+  ['sct', 'http://snomed.info/sct'],
+  ['loinc', 'http://loinc.org'],
+])
+
+/**
+ * Environment variables every evaluation defines. The static analyzer resolves
+ * and protects exactly these names, so keep this list next to the code that
+ * seeds them (createContext) — a builtin added here is known there for free.
+ */
+export const BUILTIN_ENV_VARIABLE_NAMES: ReadonlySet<string> = new Set([
+  ...BUILTIN_CONSTANTS.keys(),
+  'context',
+  'resource',
+  'rootResource',
+])
+
+/**
+ * Env records accept variable names with or without the leading `%`
+ * (`{ '%loinc': … }` or `{ loinc: … }`). Normalize to bare names — the form the
+ * context binds — so code that merges or overrides env records treats both
+ * spellings as one namespace. Later entries win on the same bare name.
+ */
+export function normalizeEnvKeys<T>(env: Record<string, T> | undefined): Record<string, T> {
+  const normalized: Record<string, T> = {}
+  for (const [name, value] of Object.entries(env ?? {})) {
+    normalized[name.startsWith('%') ? name.slice(1) : name] = value
+  }
+  return normalized
+}
+
+/**
+ * An env record as the collections a context binds: names normalized, values
+ * wrapped. The one conversion from the host's env shape into the engine's, used
+ * both to seed a context and to build a function's own overlay.
+ */
+export function envCollections(env: Record<string, unknown> | undefined): Map<string, TypedValue[]> {
+  const collections = new Map<string, TypedValue[]>()
+  for (const [name, value] of Object.entries(normalizeEnvKeys(env))) {
+    collections.set(name, toCollection(value))
+  }
+  return collections
+}
+
+/** Merge two env-shaped records per name: both key spellings normalize first, and `override` wins. */
+export function mergeEnvKeys<T>(
+  base: Record<string, T> | undefined,
+  override: Record<string, T> | undefined
+): Record<string, T> {
+  return { ...normalizeEnvKeys(base), ...normalizeEnvKeys(override) }
+}
+
+export function createContext(options: {
+  root: TypedValue[]
+  env?: Record<string, unknown> | undefined
+  model?: ModelProvider | undefined
+  now?: Date | undefined
+  trace?: ((name: string, values: TypedValue[]) => void) | undefined
+  functions?: Record<string, HostFunction> | undefined
+  regex?: RegexEngine | undefined
+}): EvaluationContext {
+  const env = new Map<string, TypedValue[]>()
+  for (const [name, url] of BUILTIN_CONSTANTS) {
+    env.set(name, [{ type: SYSTEM_STRING, value: url }])
+  }
+  env.set('context', options.root)
+  // FHIR-defined variables; contained-resource re-rooting is a later refinement.
+  env.set('resource', options.root)
+  env.set('rootResource', options.root)
+  for (const [name, value] of envCollections(options.env)) {
+    env.set(name, value)
+  }
+  const hostFunctions = new Map<string, HostFunction>()
+  for (const [name, fn] of Object.entries(options.functions ?? {})) {
+    // Overriding a built-in would silently change spec behavior — fail loudly.
+    if (builtinFunctions.has(name)) {
+      throw new FhirPathTypeError(`Cannot override the built-in function '${name}'`)
+    }
+    hostFunctions.set(name, fn)
+  }
+  return {
+    root: options.root,
+    env,
+    model: options.model,
+    now: options.now ?? new Date(),
+    trace: options.trace ?? (() => {}),
+    variables: new Map(),
+    functions: hostFunctions,
+    activeExpressionFunctions: new Set(),
+    regex: options.regex,
+    frame: { parent: undefined, thisValue: options.root, index: undefined, total: undefined },
+  }
+}
+
+/**
+ * Adds environment values for one expression function body. Existing variables
+ * still take priority because variable lookup happens before environment lookup.
+ */
+export function withEnvOverlay(
+  context: EvaluationContext,
+  overlay: ReadonlyMap<string, TypedValue[]>
+): EvaluationContext {
+  return { ...context, env: new Map([...context.env, ...overlay]) }
+}
+
+/** A context whose defineVariable() scope is detached from the parent chain. */
+export function forkVariables(context: EvaluationContext): EvaluationContext {
+  return { ...context, variables: new Map(context.variables) }
+}
+
+/** Resolve `%name`; referencing an undefined environment variable is an error (spec §9). */
+export function resolveEnvironmentVariable(context: EvaluationContext, name: string): TypedValue[] {
+  const value = context.variables.get(name) ?? context.env.get(name)
+  if (value !== undefined) {
+    return value
+  }
+  // FHIR-defined families: %`vs-[name]` and %`ext-[name]` expand to HL7 urls.
+  if (name.startsWith('vs-')) {
+    return [{ type: SYSTEM_STRING, value: `http://hl7.org/fhir/ValueSet/${name.slice(3)}` }]
+  }
+  if (name.startsWith('ext-')) {
+    return [{ type: SYSTEM_STRING, value: `http://hl7.org/fhir/StructureDefinition/${name.slice(4)}` }]
+  }
+  throw new FhirPathTypeError(`Undefined environment variable %${name}`)
+}
+
+/** Run `body` with a frame binding `$this` (and optionally `$index` / `$total`). */
+export function withFrame<T>(
+  context: EvaluationContext,
+  frame: { thisValue: TypedValue[]; index?: number; total?: TypedValue[] },
+  body: (context: EvaluationContext) => T
+): T {
+  const child: Frame = {
+    parent: context.frame,
+    thisValue: frame.thisValue,
+    index: frame.index,
+    total: frame.total,
+  }
+  return body({ ...context, frame: child, variables: new Map(context.variables) })
+}