fhirpath-ts 0.2.1 → 0.2.2

package/src/analyzer/analyze.ts

@@ -34,9 +34,12 @@ import {
   type FunctionSignature,
   type InputSpec,
   singleAnd,
+  singleState,
+  singletonOrder,
   unionStates,
   withSingle,
 } from './signatures.ts'
+import { SOURCE_VARIABLE_DEFAULTS, type SourceVariableDefaults, type SourceVariablePlan } from './source-options.ts'
 
 export interface AnalyzerDiagnostic {
   severity: 'error' | 'warning'
@@ -91,6 +94,8 @@ export interface AnalyzeOptions {
   functions?: Record<string, DeclaredFunction>
   /** Host-supplied environment variables by name (with or without the leading `%`). */
   variables?: Record<string, DeclaredVariable>
+  /** Report navigation that remains unchecked because a declared host variable has no type. */
+  reportUnchecked?: boolean
 }
 
 /** Internal strict-analysis options whose variables may retain exact runtime focus types. */
@@ -106,6 +111,8 @@ export interface RuntimeAnalyzeOptions extends Omit<AnalyzeOptions, 'variables'>
 interface StaticState {
   types: string[] | undefined
   single: boolean | undefined
+  /** True: ordered. False: unordered. Undefined: ordering is unknown. */
+  ordered: boolean | undefined
   /** Exact runtime focus types, present only while strict analysis can still prove them. */
   exactTypes?: string[]
   /**
@@ -116,16 +123,22 @@ interface StaticState {
   targets?: string[]
   /** True until the raw input has been narrowed or navigated through the model. */
   rawInput?: boolean
+  /** Untyped host variable whose first element navigation cannot be checked. */
+  opaqueVariable?: string
 }
 
-const UNKNOWN: StaticState = { types: undefined, single: undefined }
+const UNKNOWN: StaticState = { types: undefined, single: undefined, ordered: undefined }
 
 /** A runtime-analyzed function result no longer has exact facts about its input focus. */
-function callResult(state: Pick<StaticState, 'types' | 'single' | 'targets'>, runtime: boolean): StaticState {
+function callResult(
+  state: Pick<StaticState, 'types' | 'single' | 'ordered' | 'targets'>,
+  runtime: boolean
+): StaticState {
   return runtime
     ? {
         types: state.types,
         single: state.single,
+        ordered: state.ordered,
         ...(state.targets !== undefined && { targets: state.targets }),
       }
     : state
@@ -152,14 +165,14 @@ function forkScope(scope: VariableScope): VariableScope {
 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`).
+   * The expression's inferred result: canonical type names, cardinality, and
+   * ordering, the same StaticState the checks run on. `types: undefined` means
+   * the analyzer cannot see through the expression (an unknown region), and an
+   * undefined `single` or `ordered` means that fact is unknown — none of these
+   * 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 }
+  result: { types: string[] | undefined; single: boolean | undefined; ordered: boolean | undefined }
   /**
    * `Type.element` paths the expression reads (local type names), deduped in
    * first-visit order — HAPI's `elementDependencies`. Lets callers know which
@@ -172,6 +185,7 @@ export interface AnalysisDetails {
 export interface AnalyzerRoot {
   types: string[] | undefined
   single: boolean | undefined
+  ordered: boolean | undefined
   /** Canonical runtime types in focus order; an empty array means an exactly empty focus. */
   exactTypes?: string[]
 }
@@ -188,32 +202,63 @@ export function analyzeExpression(expression: string, options?: AnalyzeOptions):
 
 /**
  * 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.
+ * does not prove which variables the later call provides. A site whose call
+ * binds variables the source cannot name (`openVariables`) may resolve any
+ * `%variable` at runtime, so an unresolved one is reported as an
+ * `unchecked-variable` warning under `reportUnchecked` instead of an error.
+ * DTO sites may also receive variables and functions from base classes, other
+ * modules, or `project()`. Such sites omit unknown-variable diagnostics and
+ * report an unknown function only when it resembles a local column. A DTO
+ * without a known root receives syntax checks only. Use `analyzeDto` when the
+ * class and engine are loaded.
  */
 export function analyzeSite(
   site: {
     expression: string
     inputType?: string
     dto?: true
+    /** Variables declared by the expression's call site, such as inline env/vars options. */
+    variables?: Readonly<Record<string, DeclaredVariable>>
+    /** The call also binds variables the source cannot name — a computed key or spread in env/vars. */
+    openVariables?: true
     /** Functions the site's file declares — a DTO's `@column` fields (see `columnFunctionDeclaration`). */
     functions?: Readonly<Record<string, DeclaredFunction>>
   },
   options?: AnalyzeOptions
 ): AnalyzerDiagnostic[] {
+  const sourceVariables = (options as { [SOURCE_VARIABLE_DEFAULTS]?: SourceVariableDefaults } | undefined)?.[
+    SOURCE_VARIABLE_DEFAULTS
+  ]
+  const variablePlan = (site as typeof site & { variablePlan?: SourceVariablePlan }).variablePlan
   const declared = { ...site.functions, ...options?.functions }
+  const variables = sourceSiteVariables(site.variables, variablePlan, options?.variables, sourceVariables)
   const merged: AnalyzeOptions = {
     ...options,
     ...(site.inputType !== undefined && { inputType: site.inputType }),
     ...(Object.keys(declared).length > 0 && { functions: declared }),
+    ...(variables !== undefined && { variables }),
   }
   const diagnostics = analyzeExpression(site.expression, merged)
   if (site.dto !== true) {
-    return site.inputType === undefined
+    if (site.openVariables === true) {
+      return diagnostics.flatMap(diagnostic => {
+        if (diagnostic.code !== 'unknown-variable') {
+          return [diagnostic]
+        }
+        if (options?.reportUnchecked !== true) {
+          return []
+        }
+        return [
+          {
+            ...diagnostic,
+            severity: 'warning' as const,
+            code: 'unchecked-variable',
+            message: `Environment variable %${diagnostic.name} was not checked: the call's env/vars names are not fully visible in source`,
+          },
+        ]
+      })
+    }
+    return site.inputType === undefined || options?.variables !== undefined
       ? diagnostics
       : diagnostics.filter(diagnostic => diagnostic.code !== 'unknown-variable')
   }
@@ -232,6 +277,42 @@ export function analyzeSite(
   })
 }
 
+/** Recreate strict evaluation's vars prefix without flattening away engine/default insertion order. */
+function sourceSiteVariables(
+  siteEnvironment: Readonly<Record<string, DeclaredVariable>> | undefined,
+  plan: SourceVariablePlan | undefined,
+  engineEnvironment: Readonly<Record<string, DeclaredVariable>> | undefined,
+  defaults: SourceVariableDefaults | undefined
+): Record<string, DeclaredVariable> | undefined {
+  if (
+    siteEnvironment === undefined &&
+    engineEnvironment === undefined &&
+    defaults === undefined &&
+    plan === undefined
+  ) {
+    return undefined
+  }
+  const variables: Record<string, DeclaredVariable> = { ...engineEnvironment, ...siteEnvironment }
+  const declarations =
+    plan?.inheritsDeclarations === false ? plan.declarations : { ...defaults?.declarations, ...plan?.declarations }
+  const valueNames = [...(defaults?.values ?? [])]
+  for (const name of plan?.values ?? []) {
+    if (!valueNames.includes(name)) {
+      valueNames.push(name)
+    }
+  }
+  const end = plan?.before === undefined ? valueNames.length : valueNames.indexOf(plan.before)
+  for (const name of valueNames.slice(0, end < 0 ? valueNames.length : end)) {
+    variables[name] = declarations[name] ?? {}
+  }
+  if (plan?.before === undefined) {
+    for (const [name, declaration] of Object.entries(declarations)) {
+      variables[name] ??= declaration
+    }
+  }
+  return variables
+}
+
 /** `analyzeExpression` plus the element paths the expression touches and its inferred result type. */
 export function analyzeExpressionDetailed(expression: string, options?: AnalyzeOptions): AnalysisDetails {
   let ast: AstNode
@@ -246,7 +327,7 @@ export function analyzeExpressionDetailed(expression: string, options?: AnalyzeO
     return {
       diagnostics: [{ severity: 'error', code: 'syntax', message: error.message, span: error.span }],
       elementDependencies: [],
-      result: { types: undefined, single: undefined },
+      result: { types: undefined, single: undefined, ordered: undefined },
     }
   }
   return analyzeAstDetailed(ast, options)
@@ -263,7 +344,7 @@ function analyzeAstDetailed(
   return {
     diagnostics: analyzer.diagnostics,
     elementDependencies: [...analyzer.dependencies],
-    result: { types: state.types, single: state.single },
+    result: { types: state.types, single: state.single, ordered: state.ordered },
   }
 }
 
@@ -287,16 +368,20 @@ class Analyzer {
   private readonly customFunctions: ReadonlyMap<string, readonly ResolvedDeclaration[]>
   private readonly declaredVariables: ReadonlyMap<string, AnalyzerVariableState>
   private readonly activeExpressionFunctions = new Set<string>()
+  private readonly reportUnchecked: boolean
 
   constructor(options: AnalyzeOptions | RuntimeAnalyzeOptions | undefined, root: AnalyzerRoot | undefined) {
     this.model = options?.model
     this.runtime = root !== undefined
+    this.reportUnchecked = options?.reportUnchecked === true
     const inputType = options?.inputType
+    // The root focus is a real collection, so its order is defined even when
+    // its types and cardinality are not.
     this.root =
       root ??
       (inputType === undefined
-        ? { types: undefined, single: undefined }
-        : { types: [this.model?.resolveType(inputType) ?? inputType], single: true })
+        ? { types: undefined, single: undefined, ordered: true }
+        : singleState([this.model?.resolveType(inputType) ?? inputType]))
     this.customFunctions = new Map(
       Object.entries(options?.functions ?? {}).map(([name, declared]) => [
         name,
@@ -312,6 +397,7 @@ class Analyzer {
     return {
       types: this.root.types,
       single: this.root.single,
+      ordered: this.root.ordered,
       rawInput: true,
       ...(this.root.exactTypes !== undefined && { exactTypes: this.root.exactTypes }),
     }
@@ -322,24 +408,21 @@ class Analyzer {
       case 'null':
         // The empty literal `{}` is statically at most one item, so it satisfies
         // singleton operands (`{} + 1`, `{} and true` are spec-legal).
-        return { types: [], single: true }
+        return singleState([])
       case 'boolean':
-        return { types: ['System.Boolean'], single: true }
+        return singleState(['System.Boolean'])
       case 'string':
-        return { types: ['System.String'], single: true }
+        return singleState(['System.String'])
       case 'number':
-        return {
-          types: [node.isLong ? 'System.Long' : node.isDecimal ? 'System.Decimal' : 'System.Integer'],
-          single: true,
-        }
+        return singleState([node.isLong ? 'System.Long' : node.isDecimal ? 'System.Decimal' : 'System.Integer'])
       case 'date':
-        return { types: ['System.Date'], single: true }
+        return singleState(['System.Date'])
       case 'dateTime':
-        return { types: ['System.DateTime'], single: true }
+        return singleState(['System.DateTime'])
       case 'time':
-        return { types: ['System.Time'], single: true }
+        return singleState(['System.Time'])
       case 'quantity':
-        return { types: ['System.Quantity'], single: true }
+        return singleState(['System.Quantity'])
       case 'external':
         return this.walkExternal(node, scope)
       case 'special':
@@ -353,6 +436,7 @@ class Analyzer {
       case 'indexer': {
         const target = this.walk(node.target, input, scope)
         const index = this.walk(node.index, input, scope)
+        this.requireOrdered(target, node.target.span, 'The indexer')
         this.requireKind(index, 'Numeric', node.index.span, 'the indexer expects a single Integer')
         return withSingle(target, true)
       }
@@ -389,7 +473,7 @@ class Analyzer {
     }
     const declared = this.declaredVariables.get(node.name)
     if (declared !== undefined) {
-      return this.declaredVariableState(declared)
+      return this.declaredVariableState(declared, node.name)
     }
     switch (node.name) {
       case 'context':
@@ -400,13 +484,13 @@ class Analyzer {
       case 'ucum':
       case 'sct':
       case 'loinc':
-        return { types: ['System.String'], single: true }
+        return singleState(['System.String'])
       default:
         break
     }
     // FHIR-defined families expand to HL7 urls: %`vs-[name]`, %`ext-[name]`.
     if (node.name.startsWith('vs-') || node.name.startsWith('ext-')) {
-      return { types: ['System.String'], single: true }
+      return singleState(['System.String'])
     }
     // A dynamically-named defineVariable() earlier in the chain may have bound
     // this name, so reporting it as undefined could be wrong — stay quiet.
@@ -420,7 +504,7 @@ class Analyzer {
     if (name === 'this') {
       return this.frames.at(-1) ?? this.rootState()
     }
-    return name === 'index' ? { types: ['System.Integer'], single: true } : UNKNOWN
+    return name === 'index' ? singleState(['System.Integer']) : UNKNOWN
   }
 
   /**
@@ -437,7 +521,7 @@ class Analyzer {
   private walkIdentifier(node: AstNode & { kind: 'identifier' }, input: StaticState): StaticState {
     // Navigating from a statically empty input yields empty — nothing to check.
     if (input.types !== undefined && input.types.length === 0) {
-      return { types: [], single: true }
+      return singleState([])
     }
     const exactTypes = input.exactTypes?.filter(type => rootTypeMatches(this.model, type, node.name))
     if (exactTypes !== undefined && exactTypes.length > 0) {
@@ -445,6 +529,7 @@ class Analyzer {
       return {
         types: types === undefined ? undefined : [...new Set(types)],
         single: input.single,
+        ordered: singletonOrder(input.single, input.ordered),
         exactTypes,
         ...(input.rawInput === true && { rawInput: true }),
       }
@@ -455,14 +540,22 @@ class Analyzer {
       const asType = this.model?.resolveType(node.name) ?? resolveSystemTypeName(node.name)
       if (asType !== undefined) {
         return {
-          types: [asType],
-          single: true,
+          ...singleState([asType]),
           ...(input.exactTypes !== undefined && {
             exactTypes: input.exactTypes.filter(type => this.model?.isSubtypeOf(type, asType) === true),
           }),
         }
       }
-      return UNKNOWN
+      if (input.opaqueVariable !== undefined && this.reportUnchecked) {
+        this.report(
+          'unchecked-navigation',
+          `Element '${node.name}' after untyped environment variable %${input.opaqueVariable} was not checked; declare the variable's type`,
+          node.span,
+          'warning',
+          node.name
+        )
+      }
+      return { ...UNKNOWN, ordered: input.ordered }
     }
     // Root rule: an identifier naming the (super)type of the context is the context.
     {
@@ -528,9 +621,14 @@ class Analyzer {
           node.name
         )
       }
-      return UNKNOWN
+      return { ...UNKNOWN, ordered: input.ordered }
+    }
+    const single = singleAnd(input.single, !isCollection)
+    const state: StaticState = {
+      types: [...new Set(found)],
+      single,
+      ordered: singletonOrder(single, input.ordered),
     }
-    const state: StaticState = { types: [...new Set(found)], single: singleAnd(input.single, !isCollection) }
     if (targets !== undefined && targets.length > 0) {
       state.targets = [...new Set(targets)]
     }
@@ -641,7 +739,11 @@ class Analyzer {
     // ofType(X) filters and as(X) casts: both narrow to the named type,
     // intersected with the known candidates.
     if ((node.name === 'ofType' || node.name === 'as') && typeTarget !== undefined) {
-      return { types: this.narrowTypes(input, typeTarget, node.span), single: input.single }
+      return {
+        types: this.narrowTypes(input, typeTarget, node.span),
+        single: input.single,
+        ordered: singletonOrder(input.single, input.ordered),
+      }
     }
     const expressionResult = this.expressionFunctionResult(node.name, custom, input, scope)
     if (expressionResult !== undefined) {
@@ -675,7 +777,7 @@ class Analyzer {
     const bodyInput = this.expressionBodyInput(declaration, input)
     if (declaration.criteria === true) {
       this.walkExpressionFunction(name, expression, declaration.variables, bodyInput, scope)
-      return { types: ['System.Boolean'], single: true }
+      return singleState(['System.Boolean'])
     }
     if (declaration.signature?.result === undefined) {
       return this.walkExpressionFunction(name, expression, declaration.variables, bodyInput, scope)
@@ -703,6 +805,7 @@ class Analyzer {
     return {
       types: [...new Set(types)],
       single: callInput.single,
+      ordered: callInput.ordered,
       ...(callInput.targets !== undefined && { targets: callInput.targets }),
     }
   }
@@ -731,7 +834,7 @@ class Analyzer {
       const bare = bareEnvironmentName(declaredName)
       // defineVariable() values have priority over environment overlays at runtime.
       if (!functionScope.vars.has(bare)) {
-        functionScope.vars.set(bare, this.declaredVariableState(variable))
+        functionScope.vars.set(bare, this.declaredVariableState(variable, bare))
       }
     }
     const diagnosticCount = this.diagnostics.length
@@ -754,13 +857,15 @@ class Analyzer {
   }
 
   /** Convert one declared environment value into the same state used for scoped variables. */
-  private declaredVariableState(declared: AnalyzerVariableState): StaticState {
+  private declaredVariableState(declared: AnalyzerVariableState, name?: string): StaticState {
     const exactTypes = this.runtime && isRuntimeAnalyzerVariable(declared) ? declared.exactTypes : undefined
     return {
       types: declared.types?.map(type => this.canonicalize(type)),
       single: declared.single,
+      ordered: singletonOrder(declared.single, declared.ordered),
       ...(declared.targets !== undefined && { targets: declared.targets.map(type => this.canonicalize(type)) }),
       ...(exactTypes !== undefined && { exactTypes }),
+      ...(declared.types === undefined && name !== undefined && { opaqueVariable: name }),
     }
   }
 
@@ -814,11 +919,14 @@ class Analyzer {
     }
   }
 
-  /** The signature's input constraints: cardinality, value kind, and declared types. */
+  /** The signature's input constraints: cardinality, ordering, value kind, and declared types. */
   private checkCallInput(node: AstNode & { kind: 'call' }, signature: FunctionSignature, input: StaticState): void {
     if (!signature.input) {
       return
     }
+    if (signature.input.ordered === true) {
+      this.requireOrdered(input, node.span, `${node.name}()`)
+    }
     // A function written for one type (a DTO's `@column`), called on a focus
     // that can never be that type. `unsatisfiedInput` holds the same rule the
     // engine applies, so the two halves agree on what counts as a mistake.
@@ -840,7 +948,7 @@ class Analyzer {
     }
     if (signature.input.kind) {
       this.requireKind(
-        { types: input.types, single: true },
+        singleState(input.types),
         signature.input.kind,
         node.span,
         `${node.name}() expects a ${signature.input.kind} input`
@@ -970,14 +1078,14 @@ class Analyzer {
       return undefined
     }
     const types = declared.result?.types?.map(type => this.canonicalize(type))
-    const single = declared.result?.single
     return {
       ...(declared.input !== undefined && { input: declared.input }),
       ...(declared.args !== undefined && { args: declared.args }),
       result: {
         kind: 'fixed',
         ...(types !== undefined && { types }),
-        ...(single !== undefined && { single }),
+        ...(declared.result?.single !== undefined && { single: declared.result.single }),
+        ...(declared.result?.ordered !== undefined && { ordered: declared.result.ordered }),
       },
     }
   }
@@ -1124,6 +1232,17 @@ class Analyzer {
     }
   }
 
+  /** Report an order-dependent operation only when the input is provably unordered. */
+  private requireOrdered(state: StaticState, span: SourceSpan, subject: string): void {
+    if (state.ordered === false && state.single !== true) {
+      this.report(
+        'order-dependent',
+        `${subject} depends on collection order, but the input collection has no defined order`,
+        span
+      )
+    }
+  }
+
   private walkTypeOp(node: AstNode & { kind: 'typeOp' }, input: StaticState, scope: VariableScope): StaticState {
     const operand = this.walk(node.operand, input, scope)
     this.requireSingle(operand, node.operand.span, `'${node.operator}' expects a single item operand`)
@@ -1291,29 +1410,42 @@ function mergedDeclaration(candidates: readonly ResolvedDeclaration[]): Resolved
   }
 }
 
-/** Every type any declaration accepts, or undefined when one of them accepts anything. */
+/**
+ * Every type any declaration accepts, or no type constraint when one of them
+ * accepts anything. An ordered input stays required when every candidate
+ * requires it — whichever declaration the call resolves to would reject an
+ * unordered focus, so keeping the requirement cannot flag valid code.
+ */
 function mergedInput(candidates: readonly ResolvedDeclaration[]): InputSpec | undefined {
+  const ordered = candidates.every(candidate => candidate.signature?.input?.ordered === true)
   const declared = candidates.map(candidate => candidate.signature?.input?.types)
-  if (declared.some(types => types === undefined)) {
+  const types = declared.some(types => types === undefined)
+    ? undefined
+    : [...new Set(declared.flatMap(types => types ?? []))]
+  if (types === undefined && !ordered) {
     return undefined
   }
-  return { types: [...new Set(declared.flatMap(types => types ?? []))] }
+  return { ...(types !== undefined && { types }), ...(ordered && { ordered: true }) }
 }
 
 /** The union of the declarations' results, unknown as soon as one of them is. */
-function mergedResult(candidates: readonly ResolvedDeclaration[]): { types?: string[]; single?: boolean } | undefined {
+function mergedResult(
+  candidates: readonly ResolvedDeclaration[]
+): { types?: string[]; single?: boolean; ordered?: boolean } | undefined {
   const union = unionStates(
     candidates.map(candidate => ({
       types: candidate.signature?.result?.types === undefined ? undefined : [...candidate.signature.result.types],
       single: candidate.signature?.result?.single,
+      ordered: singletonOrder(candidate.signature?.result?.single, candidate.signature?.result?.ordered),
     }))
   )
-  if (union.types === undefined && union.single === undefined) {
+  if (union.types === undefined && union.single === undefined && union.ordered === undefined) {
     return undefined
   }
   return {
     ...(union.types !== undefined && { types: union.types }),
     ...(union.single !== undefined && { single: union.single }),
+    ...(union.ordered !== undefined && { ordered: union.ordered }),
   }
 }
 

package/src/analyzer/declarations.ts

@@ -7,11 +7,21 @@ import { OBJECT_TYPE, toCollection, type TypedValue, typeLocalName } from '../va
 export interface AnalyzerVariable {
   types?: string[]
   single?: boolean
+  /** True: ordered. False: unordered. Omit when ordering is unknown. */
+  ordered?: boolean
   targets?: string[]
 }
 
+/** Projection variables supplied by the runtime for every row. */
+export const PROJECT_ROW_VARIABLES: Readonly<Record<'rowIndex' | 'rowTotal', AnalyzerVariable>> = {
+  rowIndex: { types: ['System.Integer'], single: true },
+  rowTotal: { types: ['System.Integer'], single: true },
+}
+
 /** Internal variable state with the exact focus types used by runtime host-function dispatch. */
 export interface RuntimeAnalyzerVariable extends AnalyzerVariable {
+  /** A runtime collection is a real array, so its order is always defined. */
+  ordered: true
   exactTypes: string[]
 }
 
@@ -41,6 +51,7 @@ export function runtimeAnalyzerVariable(
   const inferred = analyzerVariableFromCollection(collection, model)
   return {
     ...(declaration === undefined ? inferred : analyzerVariable(declaration)),
+    ordered: true,
     exactTypes: collection.map(item => item.type),
   }
 }
@@ -54,6 +65,7 @@ function analyzerVariableFromCollection(
   return {
     ...(types !== undefined && types.length > 0 && { types }),
     single: collection.length <= 1,
+    ordered: true,
   }
 }