fhirpath-ts 0.2.0 → 0.2.2

package/src/sites/index.ts

@@ -12,14 +12,16 @@ import type TS from 'typescript'
 
 import {
   CALL_SITES,
+  callExpressionCandidates,
   type ClassHeritage,
   columnFunctionDeclaration,
   constructsEngine,
   declaredColumnOverloads,
   DTO_BASE_NAME,
   dtoRootsOf,
+  ENGINE_CLASS_NAME,
   type ExpressionAst,
-  expressionEntries,
+  type ExpressionProperty,
   type FileColumnFunction,
   isCheckedCall,
   isCheckedTag,
@@ -27,7 +29,6 @@ import {
   type LocalModuleOptions,
   rootOf,
   type SiteContext,
-  siteContext,
   type SourceBindings,
   TAG_NAME,
 } from '../analyzer/expression-policy.ts'
@@ -45,19 +46,52 @@ export interface ExpressionSite {
   inputType?: string
   /** A DTO member site, which `analyzeSite` checks with source-only limits. */
   dto?: true
+  /** Inline per-call environment and row-variable declarations visible to this expression. */
+  variables?: NonNullable<SiteContext['variables']>
+  /** Ordered per-call vars, interpreted together with loaded engine defaults by analyzeSite. */
+  variablePlan?: NonNullable<SiteContext['variablePlan']>
+  /** The call binds variables the source cannot name (a computed key or spread) — see `SiteContext`. */
+  openVariables?: true
   /** Callable DTO columns declared in the same file. */
   functions?: Readonly<Record<string, FileColumnFunction>>
 }
 
+export interface SkippedExpressionSite {
+  /** Stable reason suitable for CLI/editor policy. */
+  reason: 'dynamic-expression' | 'unrecognized-receiver'
+  message: string
+  line: number
+  column: number
+}
+
+export interface DtoSourceDeclaration {
+  name: string
+  line: number
+  column: number
+  /** True when importing the module can enumerate this class, directly or through an exported subclass. */
+  loadable: boolean
+}
+
+export interface SiteScanResult {
+  sites: ExpressionSite[]
+  skipped: SkippedExpressionSite[]
+  dtoDeclarations: DtoSourceDeclaration[]
+}
+
 /** Finds every static FHIRPath expression in one source file. */
 export type SiteFinder = (sourceText: string, fileName: string, options?: LocalModuleOptions) => ExpressionSite[]
 
+/** Scans expressions plus coverage gaps that a caller may choose to report. */
+export type SiteScanner = (sourceText: string, fileName: string, options?: LocalModuleOptions) => SiteScanResult
+
 /**
  * Creates a finder for the calls and tags in `CALL_SITES`. DTO fields include a
  * root type when the class declares one, and each column is exposed as a local
  * function declaration. Dynamic expressions are skipped.
  */
-export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
+export function createSiteScanner(ts: TypeScriptApi, program?: TS.Program): SiteScanner {
+  const checker = program?.getTypeChecker()
+  const engineSymbolsByOptions = new Map<string, ReadonlySet<TS.Symbol>>()
   /** How the shared shape extractor reads TypeScript AST nodes. */
   const tsAst: ExpressionAst<TS.Node> = {
     string: node => (ts.isStringLiteralLike(node) ? { node, expression: node.text } : undefined),
@@ -65,15 +99,33 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
       node.kind === ts.SyntaxKind.TrueKeyword ? true : node.kind === ts.SyntaxKind.FalseKeyword ? false : undefined,
     properties: node =>
       ts.isObjectLiteralExpression(node)
-        ? node.properties
-            .filter(ts.isPropertyAssignment)
-            .map(property => ({ name: propertyKeyName(property.name), value: property.initializer }))
+        ? node.properties.flatMap<ExpressionProperty<TS.Node>>(property => {
+            if (ts.isPropertyAssignment(property)) {
+              return [{ name: propertyKeyName(property.name), value: property.initializer }]
+            }
+            if (ts.isShorthandPropertyAssignment(property)) {
+              return [{ name: property.name.text, value: property.name }]
+            }
+            if (ts.isSpreadAssignment(property)) {
+              return [{ name: undefined, value: property.expression, spread: true as const }]
+            }
+            // Methods and accessors create enumerable own properties too. Their
+            // values are dynamic to source analysis, but their names still make
+            // env/vars scopes complete when every key is known.
+            return 'name' in property ? [{ name: propertyKeyName(property.name), value: property }] : []
+          })
         : undefined,
     elements: node => (ts.isArrayLiteralExpression(node) ? [...node.elements] : undefined),
   }
 
-  /** Statically-known property key (`path` in `{ path: ... }` or `{ 'path': ... }`), undefined when computed. */
+  /**
+   * Statically-known property key: `path` in `{ path: ... }`, `{ 'path': ... }`,
+   * or `{ ['path']: ... }`; undefined for other computed keys.
+   */
   function propertyKeyName(name: TS.PropertyName): string | undefined {
+    if (ts.isComputedPropertyName(name)) {
+      return ts.isStringLiteral(name.expression) ? name.expression.text : undefined
+    }
     return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined
   }
 
@@ -118,7 +170,8 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
   /** Collects imports, engine locals, rebound names, and DTO class roots before extracting sites. */
   function collectFile(
     source: TS.SourceFile,
-    options: LocalModuleOptions
+    options: LocalModuleOptions,
+    engineSymbols: ReadonlySet<TS.Symbol>
   ): {
     bindings: SourceBindings
     dtoRoots: ReadonlyMap<string, string>
@@ -164,12 +217,20 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
         ) {
           const set = constructsEngine(node.initializer.expression.text, bindings) ? trusted : rebound
           set.add(node.name.text)
+        } else if (ts.isIdentifier(node.name) && isEngineExpression(node.name, engineSymbols)) {
+          trusted.add(node.name.text)
+          foreign.delete(node.name.text)
         } else {
           // Catch clauses reach here too: `catch (r4)` is a VariableDeclaration.
           addBindingNames(node.name, rebound)
         }
       } else if (ts.isParameter(node)) {
-        addBindingNames(node.name, rebound)
+        if (ts.isIdentifier(node.name) && isEngineExpression(node.name, engineSymbols)) {
+          trusted.add(node.name.text)
+          foreign.delete(node.name.text)
+        } else {
+          addBindingNames(node.name, rebound)
+        }
       } else if (
         (ts.isFunctionDeclaration(node) ||
           ts.isFunctionExpression(node) ||
@@ -185,6 +246,115 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
     return { bindings, dtoRoots: dtoRootsOf([...heritage.values()]), heritage }
   }
 
+  /** Package engine declarations reached through a real `fhirpath-ts` import. */
+  function collectTrustedEngineSymbols(options: LocalModuleOptions): ReadonlySet<TS.Symbol> {
+    const symbols = new Set<TS.Symbol>()
+    if (checker === undefined || program === undefined) {
+      return symbols
+    }
+    const resolvedSymbol = (initial: TS.Symbol | undefined): TS.Symbol | undefined => {
+      let symbol = initial
+      const seen = new Set<TS.Symbol>()
+      while (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0 && !seen.has(symbol)) {
+        seen.add(symbol)
+        symbol = checker.getAliasedSymbol(symbol)
+      }
+      return symbol
+    }
+    const resolved = (node: TS.Node): TS.Symbol | undefined => resolvedSymbol(checker.getSymbolAtLocation(node))
+    for (const source of program.getSourceFiles()) {
+      for (const statement of source.statements) {
+        if (
+          !ts.isImportDeclaration(statement) ||
+          !ts.isStringLiteral(statement.moduleSpecifier) ||
+          isForeignModule(statement.moduleSpecifier.text, options)
+        ) {
+          continue
+        }
+        const bindings = statement.importClause?.namedBindings
+        if (bindings === undefined) {
+          continue
+        }
+        if (ts.isNamedImports(bindings)) {
+          for (const element of bindings.elements) {
+            if ((element.propertyName ?? element.name).text === ENGINE_CLASS_NAME) {
+              const symbol = resolved(element.name)
+              if (symbol !== undefined) {
+                symbols.add(symbol)
+              }
+            }
+          }
+          continue
+        }
+        const module = resolved(bindings.name)
+        const symbol =
+          module === undefined
+            ? undefined
+            : checker.getExportsOfModule(module).find(entry => entry.name === ENGINE_CLASS_NAME)
+        if (symbol !== undefined) {
+          symbols.add(resolvedSymbol(symbol) ?? symbol)
+        }
+      }
+    }
+    return symbols
+  }
+
+  function engineSymbolsFor(options: LocalModuleOptions): ReadonlySet<TS.Symbol> {
+    const key = JSON.stringify({ packages: options.packages, localImports: options.localImports === true })
+    const cached = engineSymbolsByOptions.get(key)
+    if (cached !== undefined) {
+      return cached
+    }
+    const symbols = collectTrustedEngineSymbols(options)
+    engineSymbolsByOptions.set(key, symbols)
+    return symbols
+  }
+
+  /** Whether TypeScript resolved an expression to this package's engine class. */
+  function isEngineExpression(node: TS.Expression, engineSymbols: ReadonlySet<TS.Symbol>): boolean {
+    if (checker === undefined || engineSymbols.size === 0 || node.getSourceFile().isDeclarationFile) {
+      return false
+    }
+    const hasEngineSymbol = (type: TS.Type, seen: Set<TS.Type>): boolean => {
+      if (seen.has(type)) {
+        return false
+      }
+      seen.add(type)
+      if (type.isUnion()) {
+        return type.types.length > 0 && type.types.every(member => hasEngineSymbol(member, new Set(seen)))
+      }
+      if (type.isIntersection()) {
+        return type.types.some(member => hasEngineSymbol(member, new Set(seen)))
+      }
+      const symbol = type.aliasSymbol ?? type.getSymbol()
+      if (symbol !== undefined && engineSymbols.has(symbol)) {
+        return true
+      }
+      const constraint = checker.getBaseConstraintOfType(type)
+      if (constraint !== undefined && constraint !== type && hasEngineSymbol(constraint, seen)) {
+        return true
+      }
+      if ((type.flags & ts.TypeFlags.Object) === 0) {
+        return false
+      }
+      const object = type as TS.ObjectType
+      if ((object.objectFlags & (ts.ObjectFlags.Class | ts.ObjectFlags.Interface | ts.ObjectFlags.Reference)) === 0) {
+        return false
+      }
+      return checker.getBaseTypes(type as TS.InterfaceType).some(base => hasEngineSymbol(base, seen))
+    }
+    return hasEngineSymbol(checker.getTypeAtLocation(node), new Set())
+  }
+
+  /** An unresolved receiver may still be an engine; a resolved non-engine is not our call site. */
+  function shouldReportUnrecognized(node: TS.Expression): boolean {
+    if (checker === undefined || node.getSourceFile().isDeclarationFile) {
+      return true
+    }
+    const flags = checker.getTypeAtLocation(node).flags
+    return (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0
+  }
+
   /** Add every identifier a binding name declares (`x`, `{ r4 }`, `[a, ...rest]`). */
   function addBindingNames(name: TS.BindingName, into: Set<string>): void {
     if (ts.isIdentifier(name)) {
@@ -220,14 +390,129 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
     return ts.isIdentifier(current) ? current.text : undefined
   }
 
-  return function findExpressionSites(
+  /** Strips source wrappers that keep an expression's runtime identity. */
+  function unwrapped(node: TS.Expression | undefined): TS.Expression | undefined {
+    let current = node
+    while (
+      current !== undefined &&
+      (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isNonNullExpression(current))
+    ) {
+      current = current.expression
+    }
+    return current
+  }
+
+  /** Class bindings made reachable by one immutable initializer or default export. */
+  function bindingTargets(node: TS.Expression | undefined): string[] {
+    const target = unwrapped(node)
+    if (target === undefined) {
+      return []
+    }
+    if (ts.isIdentifier(target)) {
+      return [target.text]
+    }
+    if (!ts.isClassExpression(target)) {
+      return []
+    }
+    // A class expression's own name is scoped to its body, not a reference to a
+    // same-named top-level class. Only its base can expose another declaration.
+    const { baseName } = heritageOf(target)
+    return baseName === undefined ? [] : [baseName]
+  }
+
+  /**
+   * The module's exported names, plus what each top-level `const` binding stands
+   * for: `export const Row = ProblemRow` makes the loader enumerate `Row`, so
+   * `ProblemRow` is reachable through it — directly, through an alias chain, or
+   * as the base of an exported anonymous class expression.
+   */
+  function moduleBindings(source: TS.SourceFile): {
+    exported: ReadonlySet<string>
+    aliases: ReadonlyMap<string, readonly string[]>
+  } {
+    const exported = new Set<string>()
+    const aliases = new Map<string, string[]>()
+    const addAlias = (from: string, to: string): void => {
+      const edges = aliases.get(from)
+      if (edges === undefined) {
+        aliases.set(from, [to])
+      } else {
+        edges.push(to)
+      }
+    }
+    const isExported = (statement: TS.Statement): boolean =>
+      (ts.canHaveModifiers(statement) ? (ts.getModifiers(statement) ?? []) : []).some(
+        modifier => modifier.kind === ts.SyntaxKind.ExportKeyword
+      )
+    for (const statement of source.statements) {
+      if (ts.isClassDeclaration(statement) && isExported(statement)) {
+        if (statement.name !== undefined) {
+          exported.add(statement.name.text)
+        } else {
+          // `export default class extends Base {}`: the loader gets the class,
+          // so its base is reachable even though neither has a bound name here.
+          const base = heritageOf(statement).baseName
+          if (base !== undefined) {
+            exported.add(base)
+          }
+        }
+      } else if (ts.isVariableStatement(statement)) {
+        const immutable = (statement.declarationList.flags & ts.NodeFlags.Const) !== 0
+        for (const declaration of statement.declarationList.declarations) {
+          if (!ts.isIdentifier(declaration.name)) {
+            continue
+          }
+          const name = declaration.name.text
+          if (isExported(statement)) {
+            exported.add(name)
+          }
+          if (immutable) {
+            for (const target of bindingTargets(declaration.initializer)) {
+              addAlias(name, target)
+            }
+          }
+        }
+      } else if (
+        ts.isExportDeclaration(statement) &&
+        statement.moduleSpecifier === undefined &&
+        statement.isTypeOnly === false &&
+        statement.exportClause !== undefined
+      ) {
+        if (ts.isNamedExports(statement.exportClause)) {
+          for (const element of statement.exportClause.elements) {
+            if (!element.isTypeOnly) {
+              exported.add((element.propertyName ?? element.name).text)
+            }
+          }
+        }
+      } else if (ts.isExportAssignment(statement)) {
+        for (const target of bindingTargets(statement.expression)) {
+          exported.add(target)
+        }
+      }
+    }
+    return { exported, aliases }
+  }
+
+  return function scanExpressionSites(
     sourceText: string,
     fileName: string,
     options: LocalModuleOptions = {}
-  ): ExpressionSite[] {
-    const source = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true)
-    const { bindings, dtoRoots, heritage } = collectFile(source, options)
+  ): SiteScanResult {
+    const programSource = program?.getSourceFile(fileName)
+    const source =
+      programSource !== undefined && programSource.text === sourceText
+        ? programSource
+        : ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true)
+    const engineSymbols = engineSymbolsFor(options)
+    const { bindings, dtoRoots, heritage } = collectFile(source, options, engineSymbols)
     const sites: ExpressionSite[] = []
+    const skipped: SkippedExpressionSite[] = []
+    const decoratedClasses = new Set<TS.ClassLikeDeclaration>()
     const functions: Record<string, FileColumnFunction> = {}
     // A site points at the first character inside the quote/backtick (node start
     // + 1), so fhirpath-check can add a diagnostic's span offsets directly. The
@@ -243,43 +528,146 @@ export function createSiteFinder(ts: TypeScriptApi): SiteFinder {
         ...context,
       })
     }
-    const visit = (node: TS.Node, classRoot: string | undefined): void => {
-      if (
-        ts.isTaggedTemplateExpression(node) &&
-        nameOf(node.tag) === TAG_NAME &&
-        isCheckedTag(receiverRoot(node.tag), bindings)
-      ) {
-        if (ts.isNoSubstitutionTemplateLiteral(node.template)) {
+    const skip = (node: TS.Node, reason: SkippedExpressionSite['reason'], message: string): void => {
+      const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source))
+      skipped.push({ reason, message, line: line + 1, column: character + 1 })
+    }
+    const visit = (
+      node: TS.Node,
+      classRoot: string | undefined,
+      enclosingClass: TS.ClassLikeDeclaration | undefined
+    ): void => {
+      if (ts.isTaggedTemplateExpression(node) && nameOf(node.tag) === TAG_NAME) {
+        if (!isCheckedTag(receiverRoot(node.tag), bindings)) {
+          if (shouldReportUnrecognized(node.tag)) {
+            skip(node.tag, 'unrecognized-receiver', 'FHIRPath tag not analyzed: its binding is not from fhirpath-ts')
+          }
+        } else if (ts.isNoSubstitutionTemplateLiteral(node.template)) {
           record(node.template.text, node.template)
+        } else {
+          skip(node.template, 'dynamic-expression', 'FHIRPath template not analyzed: substitutions make it dynamic')
         }
       } else if (ts.isCallExpression(node)) {
         const callee = nameOf(node.expression)
         const policy = callee === undefined ? undefined : CALL_SITES.get(callee)
         const argument = policy && (node.arguments[policy.argIndex] as TS.Expression | undefined)
-        if (
-          callee !== undefined &&
-          policy !== undefined &&
-          argument !== undefined &&
-          isCheckedCall(policy, callee, receiverRoot(node.expression), bindings)
-        ) {
-          const declares = policy.declaresField
-          const field = declares === undefined ? undefined : decoratedFieldName(node)
-          if (declares !== undefined && field !== undefined) {
-            functions[field] = declaredColumnOverloads(
-              functions[field],
-              columnFunctionDeclaration<TS.Node>(declares, node.arguments[1], tsAst, classRoot)
-            )
-          }
-          const context = siteContext<TS.Node>(policy, index => node.arguments[index], classRoot, tsAst)
-          for (const entry of expressionEntries<TS.Node>(argument, policy.shape, tsAst)) {
-            record(entry.expression, entry.node, context)
+        if (callee !== undefined && policy !== undefined && argument !== undefined) {
+          const typedEngineReceiver =
+            ts.isPropertyAccessExpression(node.expression) &&
+            isEngineExpression(node.expression.expression, engineSymbols)
+          const checked = isCheckedCall(policy, callee, receiverRoot(node.expression), bindings, {
+            ...(typedEngineReceiver && { engine: true }),
+          })
+          if (!checked) {
+            const receiver = receiverRoot(node.expression)
+            const receiverExpression = ts.isPropertyAccessExpression(node.expression)
+              ? node.expression.expression
+              : node.expression
+            if (shouldReportUnrecognized(receiverExpression)) {
+              skip(
+                node.expression,
+                'unrecognized-receiver',
+                `${callee}(...) expression not analyzed: ${
+                  receiver === undefined
+                    ? `binding '${callee}' is not recognized as fhirpath-ts`
+                    : `receiver '${receiver}' is not recognized as a FhirPathEngine`
+                }`
+              )
+            }
+          } else {
+            const declares = policy.declaresField
+            const field = declares === undefined ? undefined : decoratedFieldName(node)
+            if (declares !== undefined && field !== undefined) {
+              if (enclosingClass !== undefined) {
+                decoratedClasses.add(enclosingClass)
+              }
+              functions[field] = declaredColumnOverloads(
+                functions[field],
+                columnFunctionDeclaration<TS.Node>(declares, node.arguments[1], tsAst, classRoot)
+              )
+            }
+            for (const candidate of callExpressionCandidates<TS.Node>(
+              policy,
+              index => node.arguments[index],
+              classRoot,
+              tsAst
+            )) {
+              if (candidate.uncheckable === 'dynamic-vars') {
+                skip(
+                  candidate.node,
+                  'dynamic-expression',
+                  `${callee}(...) var expressions not analyzed: their final names, values, or order are dynamic`
+                )
+              } else if (candidate.expression === undefined) {
+                skip(
+                  candidate.node,
+                  'dynamic-expression',
+                  candidate.source === 'option-var'
+                    ? `${callee}(...) var expression not analyzed: it is not a string literal`
+                    : `${callee}(...) expression not analyzed: it is not a string literal`
+                )
+              } else {
+                record(candidate.expression, candidate.node, candidate.context)
+              }
+            }
           }
         }
       }
       const nested = ts.isClassLike(node) ? rootOf(heritage.get(node), dtoRoots) : classRoot
-      ts.forEachChild(node, child => visit(child, nested))
+      const nestedClass = ts.isClassLike(node) ? node : enclosingClass
+      ts.forEachChild(node, child => visit(child, nested, nestedClass))
+    }
+    visit(source, undefined, undefined)
+    const { exported, aliases } = moduleBindings(source)
+    const classByName = new Map(
+      [...heritage.entries()].flatMap(([node, value]) =>
+        ts.isClassLike(node) && value.name !== undefined ? [[value.name, value] as const] : []
+      )
+    )
+    // From every exported binding, follow alias and extends edges: what the
+    // loader enumerates under any name makes every class behind it analyzable.
+    const reachesExport = (name: string): boolean => {
+      const seen = new Set<string>()
+      const frontier = [...exported]
+      while (frontier.length > 0) {
+        const current = frontier.pop() as string
+        if (current === name) {
+          return true
+        }
+        if (seen.has(current)) {
+          continue
+        }
+        seen.add(current)
+        const base = classByName.get(current)?.baseName
+        if (base !== undefined) {
+          frontier.push(base)
+        }
+        frontier.push(...(aliases.get(current) ?? []))
+      }
+      return false
+    }
+    const dtoDeclarations = [...decoratedClasses].flatMap(node => {
+      const nameNode = node.name
+      // Runtime module discovery can only miss top-level module-local classes.
+      // A class inside a factory is reached through whatever class the factory
+      // returns, rather than as a module export with its source name.
+      if (nameNode === undefined || node.parent !== source) {
+        return []
+      }
+      const name = nameNode.text
+      const { line, character } = source.getLineAndCharacterOfPosition(nameNode.getStart(source))
+      return [{ name, line: line + 1, column: character + 1, loadable: reachesExport(name) }]
+    })
+    return {
+      sites: Object.keys(functions).length === 0 ? sites : sites.map(site => ({ ...site, functions })),
+      skipped,
+      dtoDeclarations,
     }
-    visit(source, undefined)
-    return Object.keys(functions).length === 0 ? sites : sites.map(site => ({ ...site, functions }))
   }
 }
+
+/** Creates the compatibility finder that returns only expressions successfully extracted. */
+export function createSiteFinder(ts: TypeScriptApi, program?: TS.Program): SiteFinder {
+  const scan = createSiteScanner(ts, program)
+  return (sourceText, fileName, options) => scan(sourceText, fileName, options).sites
+}

package/src/typed/infer.ts

@@ -32,9 +32,9 @@ export type FhirpathTypeDeclarations = Readonly<Record<string, FhirpathTypeDecla
 export type FhirpathFunctionDeclaration =
   | {
       readonly signature?: {
-        readonly input?: { readonly types?: readonly string[] }
+        readonly input?: { readonly types?: readonly string[]; readonly ordered?: boolean }
         readonly args?: readonly string[]
-        readonly result?: { readonly types?: readonly string[]; readonly single?: boolean }
+        readonly result?: { readonly types?: readonly string[]; readonly single?: boolean; readonly ordered?: boolean }
       }
       readonly expression?: string | { readonly source: string }
       readonly criteria?: boolean