fhirpath-ts 0.0.0-bootstrap.0

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "fhirpath-ts",
+  "version": "0.0.0-bootstrap.0",
+  "description": "TypeScript-native FHIRPath engine with compile-time type inference and a spec §11 static analyzer.",
+  "keywords": [
+    "fhirpath",
+    "fhir",
+    "hl7",
+    "healthcare",
+    "interoperability",
+    "r4",
+    "static-analysis",
+    "type-inference",
+    "eslint-plugin",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vinta Software (https://github.com/vintasoftware)",
+  "homepage": "https://github.com/vintasoftware/fhirpath-ts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vintasoftware/fhirpath-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vintasoftware/fhirpath-ts/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": [
+    "./dist/functions/*.js",
+    "./src/functions/*.ts",
+    "./dist/cli/*.js",
+    "./src/cli/*.ts"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./r4": {
+      "types": "./dist/r4/index.d.ts",
+      "default": "./dist/r4/index.js"
+    },
+    "./analyzer": {
+      "types": "./dist/analyzer/index.d.ts",
+      "default": "./dist/analyzer/index.js"
+    },
+    "./eslint": {
+      "types": "./dist/eslint/index.d.ts",
+      "default": "./dist/eslint/index.js"
+    },
+    "./sites": {
+      "types": "./dist/sites/index.d.ts",
+      "default": "./dist/sites/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "fhirpath-check": "./dist/cli/fhirpath-check.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/testing",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "typescript": ">=5.0.0 <7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^9.39.2",
+    "@medplum/definitions": "5.1.24",
+    "@medplum/fhirtypes": "5.1.24",
+    "@types/estree": "^1.0.9",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "fast-check": "^4.9.0",
+    "fast-xml-parser": "^5.3.2",
+    "fhirpath": "^4.11.0",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.4",
+    "npm": "11.11.0",
+    "prettier": "^3.6.2",
+    "publint": "^0.3.23",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,jsonc}": [
+      "prettier --write"
+    ]
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "check:type-perf": "node scripts/check-type-perf.ts",
+    "check:package": "node scripts/check-package.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "lint": "eslint . && prettier --check .",
+    "lint:fix": "eslint --fix . && prettier --write .",
+    "format": "prettier --write .",
+    "generate:r4": "node scripts/generate-r4-model.ts",
+    "check:fhirpath": "node src/cli/fhirpath-check.ts"
+  }
+}

package/src/analyzer/analyze-dto.ts

@@ -0,0 +1,195 @@
+import { columnResultType } from '../api/column-signature.ts'
+import { type ColumnSpec, type DtoClass, dtoDefinition } from '../api/dto.ts'
+import type { ModelProvider } from '../model/provider.ts'
+import { valueKindOfTypeName } from '../values/type-compat.ts'
+import {
+  analyzeExpressionDetailed,
+  type AnalyzeOptions,
+  type AnalyzerDiagnostic,
+  type DeclaredFunction,
+  type DeclaredVariable,
+} from './analyze.ts'
+
+/** One `analyzeDto` finding: an analyzer diagnostic plus the class member it came from. */
+export interface DtoDiagnostic extends AnalyzerDiagnostic {
+  /** The column field name, or `vars.<name>` for a DTO var. */
+  member: string
+  /** The expression that produced the finding, so a reporter can locate it in source. */
+  expression: string
+}
+
+/** Engine context read by the analyzer without importing the engine implementation. */
+export interface AnalyzedContext {
+  readonly defaults: { model?: ModelProvider; functions?: Record<string, DeclaredFunction>; env?: object }
+}
+
+/** A context that also knows which DTOs it registered, which is what a sweep needs. */
+export interface AnalyzedEngine extends AnalyzedContext {
+  readonly dtos: readonly DtoClass[]
+}
+
+/** `analyzeDto` options, with the engine the DTO belongs to as a shortcut for its context. */
+export interface AnalyzeDtoOptions extends AnalyzeOptions {
+  /** Engine model, functions, and environment names used while checking the DTO. */
+  engine?: AnalyzedContext
+}
+
+/**
+ * The analyzer context for a DTO: what its engine supplies, with the caller's
+ * own options layered on top *per name* — one function or variable a host
+ * declares must not displace the engine's whole table, or a valid column call
+ * would be reported as unresolved. `model` and `inputType` are single values, so
+ * there the caller simply wins.
+ */
+function contextOf(options: AnalyzeDtoOptions | undefined): AnalyzeOptions {
+  const { engine, ...caller } = options ?? {}
+  if (engine === undefined) {
+    return caller
+  }
+  const { model, functions, env } = engine.defaults
+  return {
+    ...(model !== undefined && { model }),
+    ...caller,
+    functions: { ...functions, ...caller.functions },
+    variables: { ...envVariables(env), ...caller.variables },
+  }
+}
+
+/** An engine's env names, declared as variables the expressions may read. */
+function envVariables(env: object | undefined): Record<string, DeclaredVariable> {
+  const variables: Record<string, DeclaredVariable> = {}
+  for (const name of Object.keys(env ?? {})) {
+    variables[bare(name)] = {}
+  }
+  return variables
+}
+
+/**
+ * Every DTO an engine registered, checked against that engine's own context —
+ * the sweep a project's checker runs, with no list to maintain: the engine
+ * already knows its `resourceDtos`. Each finding names the class it came from.
+ * DTOs the engine does not register (row shapes you only ever project) are not
+ * reachable from here; pass those to `analyzeDto` yourself, or list them.
+ */
+export function analyzeEngineDtos(
+  engine: AnalyzedEngine,
+  options?: AnalyzeOptions
+): (DtoDiagnostic & { dto: string })[] {
+  return engine.dtos.flatMap(dto =>
+    analyzeDto(dto, { ...options, engine }).map(finding => ({ ...finding, dto: dto.name }))
+  )
+}
+
+/**
+ * Checks a DTO's columns, criteria, and variables. The DTO type is the input
+ * context. DTO environment names, caller environment names, and row variables
+ * are declared automatically. Variables are checked in order. Declared column
+ * types and enums are compared with the analyzer result.
+ */
+export function analyzeDto(dto: DtoClass, options?: AnalyzeDtoOptions): DtoDiagnostic[] {
+  const definition = dtoDefinition(dto)
+  const context = contextOf(options)
+  const inputType = context.inputType ?? definition.fhirType
+  const declared: Record<string, DeclaredVariable> = {
+    rowIndex: { types: ['System.Integer'], single: true },
+    rowTotal: { types: ['System.Integer'], single: true },
+  }
+  for (const name of [...Object.keys(definition.env ?? {}), ...(definition.callerEnv ?? [])]) {
+    declared[bare(name)] = {}
+  }
+  const diagnostics: DtoDiagnostic[] = []
+  const analyze = (member: string, expression: string, column?: ColumnSpec): void => {
+    const perExpression: AnalyzeOptions = {
+      ...context,
+      ...(inputType !== undefined && { inputType }),
+      variables: { ...declared, ...context.variables },
+    }
+    const { diagnostics: found, result } = analyzeExpressionDetailed(expression, perExpression)
+    for (const diagnostic of found) {
+      diagnostics.push({ member, expression, ...diagnostic })
+    }
+    const mismatch = column === undefined ? undefined : declaredTypeMismatch(column, result.types, context)
+    if (mismatch !== undefined) {
+      // The conflicting field declaration is outside the expression, so mark the whole expression.
+      diagnostics.push({
+        member,
+        expression,
+        severity: 'error',
+        code: 'column-type',
+        message: mismatch,
+        span: { start: 0, end: expression.length, line: 1, column: 1 },
+      })
+    }
+  }
+  for (const [name, value] of Object.entries(definition.vars ?? {})) {
+    const source = typeof value === 'string' ? value : sourceOf(value)
+    if (source !== undefined) {
+      // A var declares no type, so there is nothing to cross-check against.
+      analyze(`vars.${bare(name)}`, source)
+    }
+    declared[bare(name)] = {}
+  }
+  for (const [name, spec] of Object.entries(definition.columns)) {
+    analyze(name, expressionOf(spec), spec)
+  }
+  return diagnostics
+}
+
+/** The expression a column reads: a criteria's `test`, else its path. */
+function expressionOf(column: ColumnSpec): string {
+  return 'test' in column ? column.test : column.path
+}
+
+/**
+ * The type a column claims its expression yields — `columnSignature`'s rule, the
+ * one the engine registers and the walkers declare, so a cross-check can never
+ * contradict a claim that was never made.
+ *
+ * A criteria claims nothing here, even though its function declares a Boolean
+ * result. The Boolean comes from the criteria rule applied to the result, not
+ * from the expression itself. `@criteria('name.given')` validly returns
+ * HumanName.given, which then reads as true.
+ */
+function claimedType(column: ColumnSpec): string | undefined {
+  return 'test' in column ? undefined : columnResultType(column)
+}
+
+/**
+ * Compares a declared column type with analyzer results. Primitive types compare
+ * by value kind; complex types use the model hierarchy. Unknown results pass.
+ */
+function declaredTypeMismatch(
+  column: ColumnSpec,
+  yielded: string[] | undefined,
+  options: AnalyzeOptions | undefined
+): string | undefined {
+  const claimed = claimedType(column)
+  if (claimed === undefined || yielded === undefined || yielded.length === 0) {
+    return undefined
+  }
+  const canonical = options?.model?.resolveType(claimed) ?? claimed
+  const claimedKind = valueKindOfTypeName(canonical)
+  const fits = yielded.some(type => {
+    if (valueKindOfTypeName(type) !== claimedKind) {
+      return false
+    }
+    if (claimedKind !== 'Complex') {
+      return true
+    }
+    const model = options?.model
+    /* v8 ignore next -- without a model the analyzer never reaches a complex FHIR type, so the model-less half cannot be exercised */
+    return model === undefined || model.isSubtypeOf(type, canonical) || model.isSubtypeOf(canonical, type)
+  })
+  return fits ? undefined : `Column declares type '${claimed}', but the expression yields ${yielded.join(' | ')}`
+}
+
+const bare = (name: string): string => (name.startsWith('%') ? name.slice(1) : name)
+
+/** A pre-compiled var's source text; a pre-bound TypedValue[] has nothing to analyze. */
+function sourceOf(value: object): string | undefined {
+  if (Array.isArray(value)) {
+    return undefined
+  }
+  const source = (value as { source?: unknown }).source
+  return typeof source === 'string' ? source : undefined
+}