babelfhir-ts 1.0.32 → 1.0.34

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="./logo.png" alt="BabelFHIR-TS Logo" width="200"/>
+  <img src="./logo_transparent.png" alt="BabelFHIR-TS Logo" width="200"/>
 </div>
 
 # BabelFHIR-TS
@@ -22,6 +22,22 @@
 - **Fast and lightweight**—minimal runtime deps; only `fhirpath` is required for validators
 - **Install any FHIR profile as a node module**—use `babelfhir-ts install` to add Implementation Guides directly to your project
 
+<!-- PARITY-BADGES:START - Do not remove or modify this section -->
+## Pipeline Parity Results
+
+BabelFHIR-TS validators achieve **100% parity** with the Firely .NET SDK validator across major Implementation Guides:
+
+![US Core 8.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-us-core.json)
+![ISiK Basis 4.0.3](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-isik-basis.json)
+![IPS 2.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-ips.json)
+![SMART 2.2.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-smart.json)
+![CH Core 5.0.0](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f/raw/badge-ch-core.json)
+
+> **11 profiles excluded** due to [Firely SDK bugs](./docs/FIRELY-VALIDATOR-BUGS.md) — validated successfully with HL7 Java Validator.
+
+📊 **[Full Report](https://gist.github.com/quotentiroler/e9bc625cfe88a0a67a73abc06660f40f)** · *Last updated: Dec 10, 2025*
+<!-- PARITY-BADGES:END -->
+
 ## Installation
 
 Install globally (recommended when using the CLI frequently):
@@ -125,6 +141,7 @@ babelfhir-ts [options] [<input> [output]]
 | `--log <level>`           | Control logging output:`none` (default), `console`, or `file`.                                                                                                |
 | `--no-cache`              | Remove the `.cache` directory once generation completes.                                                                                                          |
 | `--no-classes`            | Skip emitting helper classes (interfaces & validators only).                                                                                                        |
+| `--cache-dir <path>`      | Custom cache directory (default:`.cache`). Also configurable via `FHIR_CACHE_ROOT` env var.                                                                     |
 | `-h, --help`              | Print usage help.                                                                                                                                                   |
 | `-v, --version`           | Print the BabelFHIR-TS version.                                                                                                                                     |
 
@@ -136,12 +153,12 @@ babelfhir-ts [options] [<input> [output]]
 
 ## Scripts for contributors
 
-| Script                         | Purpose                                                                      |
-| ------------------------------ | ---------------------------------------------------------------------------- |
-| `npm run generate`           | Execute the CLI against the local `input/` folder and refresh `output/`. |
-| `npm run generate:check`     | End-to-end check: generate, type-check, and lint the emitted output.         |
-| `npm test`                   | Type-check and run all Vitest suites (coverage enabled).                     |
-| `npm test validatorParity`   | Run validator parity tests against Firely .NET SDK validator.                |
+| Script                      | Purpose                                                                      |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| `npm run generate`        | Execute the CLI against the local `input/` folder and refresh `output/`. |
+| `npm run generate:check`  | End-to-end check: generate, type-check, and lint the emitted output.         |
+| `npm test`                | Type-check and run all Vitest suites (coverage enabled).                     |
+| `npm test pipelineParity` | Run pipeline parity tests against Firely .NET SDK validator.                 |
 
 ## Caching notes
 
@@ -166,6 +183,7 @@ BabelFHIR-TS is a code generation tool that parses FHIR StructureDefinitions and
 ### Validation Scope
 
 The generated `validate()` methods DO check:
+
 - **FHIRPath constraints** from StructureDefinition invariants
 - **Cardinality rules** (min/max occurrences)
 - **Required fields** from profiles
@@ -174,12 +192,13 @@ The generated `validate()` methods DO check:
 - **Data type correctness** (string, number, boolean, etc.)
 
 The generated validators DO NOT check:
+
 - **Terminology validation** (ValueSet expansion, code system membership) - requires terminology server
 - **Reference resolution** (checking that referenced resources exist) - requires FHIR server
 - **Complex discriminator types** (type, profile, exists, position) - only pattern/value discriminators supported
 - **Cross-resource business rules** - application-specific logic
 
-For comprehensive conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) or [Firely .NET SDK](https://fire.ly/products/firely-net-sdk/).
+For comprehensive conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator)!
 
 ### TypeScript Limitations
 
@@ -190,14 +209,14 @@ For comprehensive conformance testing, use the official [HL7 FHIR Validator](htt
 ### Generated Helper Methods
 
 - **`random()` is not fully conformant**: The generated `.random()` methods create test data that satisfies TypeScript types and basic cardinality, but **do not guarantee** fully valid FHIR resources. Random data may violate:
+
   - Complex FHIRPath invariants
   - ValueSet bindings (codes are randomly chosen from required bindings but not guaranteed to be semantically correct)
   - Profile-specific business rules
   - Reference integrity constraints
-  
-  Use `random()` for development, testing, and prototyping, but always validate production data on the FHIR server side.
 
-- **`validate()` parity**: The generated validation methods execute FHIRPath expressions and check constraints from StructureDefinitions, but are **only guaranteed to match** the Firely .NET SDK validator for scenarios covered by our test suite (see GitHub actions). Edge cases, complex slicing patterns, or profiles not in our test pipeline may produce different results. For production conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) or [Firely .NET SDK](https://fire.ly/products/firely-net-sdk/) as the source of truth.
+  Use `random()` for development, testing, and prototyping, but always validate production data on the FHIR server side.
+- **`validate()` parity**: The generated validation methods execute FHIRPath expressions and check constraints from StructureDefinitions, but are **only guaranteed to match** the Firely .NET SDK validator for scenarios covered by our test suite (see GitHub actions). Edge cases, complex slicing patterns, or profiles not in our test pipeline may produce different results. For production conformance testing, use the official [HL7 FHIR Validator](https://confluence.hl7.org/display/FHIR/Using+the+FHIR+Validator) as the source of truth.
 
 ### FHIR Version Support
 

package/out/generator/cacheConfig.js

@@ -0,0 +1,181 @@
+/**
+ * Centralized cache configuration for the FHIR TypeScript generator.
+ *
+ * This module provides a unified approach to cache management across the project.
+ *
+ * Cache Structure:
+ *   Root cache directory: configurable via environment variable or defaults to .cache
+ *   FHIR packages: cacheRoot/.fhir/packages/packageName@version/
+ *   FHIR resources (StructureDefinitions): cacheRoot/fhir-resources/
+ *   Temporary files: cacheRoot/tmp/
+ *
+ * Environment Variables:
+ *   FHIR_CACHE_ROOT: Override the root cache directory (useful for CI)
+ *   FHIR_CACHE_LOCAL: If set to "true", use package-local cache (in output directory)
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+// Module-level state for cache configuration
+let currentConfig = null;
+/**
+ * Get the default cache root directory based on environment
+ */
+function getDefaultCacheRoot() {
+    // Check for explicit override
+    if (process.env.FHIR_CACHE_ROOT) {
+        return process.env.FHIR_CACHE_ROOT;
+    }
+    // Default to .cache in current working directory
+    return path.join(process.cwd(), '.cache');
+}
+/**
+ * Get the cache mode based on environment
+ */
+function getDefaultCacheMode() {
+    if (process.env.FHIR_CACHE_LOCAL === 'true') {
+        return 'local';
+    }
+    return 'global';
+}
+/**
+ * Initialize or get the current cache configuration
+ */
+export function getCacheConfig() {
+    if (!currentConfig) {
+        currentConfig = {
+            rootDir: getDefaultCacheRoot(),
+            mode: getDefaultCacheMode(),
+        };
+    }
+    return currentConfig;
+}
+/**
+ * Override the cache configuration (useful for testing or CLI options)
+ */
+export function setCacheConfig(config) {
+    const current = getCacheConfig();
+    currentConfig = {
+        ...current,
+        ...config,
+    };
+}
+/**
+ * Reset cache configuration to defaults (useful for testing)
+ */
+export function resetCacheConfig() {
+    currentConfig = null;
+}
+/**
+ * Get the FHIR packages cache directory
+ * This is where downloaded FHIR packages (tgz files) are stored
+ */
+export function getFhirPackagesCacheDir() {
+    const config = getCacheConfig();
+    return path.join(config.rootDir, '.fhir', 'packages');
+}
+/**
+ * Get the FHIR resources cache directory
+ * This is where fetched StructureDefinitions are cached
+ */
+export function getFhirResourcesCacheDir() {
+    const config = getCacheConfig();
+    return path.join(config.rootDir, 'fhir-resources');
+}
+/**
+ * Get the temporary files directory
+ */
+export function getTempCacheDir() {
+    const config = getCacheConfig();
+    return path.join(config.rootDir, 'tmp');
+}
+/**
+ * Get the path for a specific FHIR package
+ * @param packageName The package name (e.g., "hl7.fhir.us.core")
+ * @param version The package version (e.g., "8.0.0")
+ */
+export function getPackageCachePath(packageName, version) {
+    const packagesDir = getFhirPackagesCacheDir();
+    return path.join(packagesDir, `${packageName}@${version}`);
+}
+/**
+ * Get the path for a package tgz file
+ * @param packageName The package name
+ * @param version The package version
+ */
+export function getPackageTgzPath(packageName, version) {
+    const packagesDir = getFhirPackagesCacheDir();
+    return path.join(packagesDir, `${packageName}-${version}.tgz`);
+}
+/**
+ * Get the path for a cached FHIR resource (StructureDefinition)
+ * @param url The canonical URL of the resource
+ */
+export function getResourceCachePath(url) {
+    const resourcesDir = getFhirResourcesCacheDir();
+    // Convert URL to safe filename
+    const filename = url.replace(/[^a-zA-Z0-9]/g, '_') + '.json';
+    return path.join(resourcesDir, filename);
+}
+/**
+ * Ensure a cache directory exists
+ */
+export function ensureCacheDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Ensure all cache directories exist
+ */
+export function ensureAllCacheDirs() {
+    ensureCacheDir(getFhirPackagesCacheDir());
+    ensureCacheDir(getFhirResourcesCacheDir());
+    ensureCacheDir(getTempCacheDir());
+}
+/**
+ * Clear a specific cache directory
+ */
+export function clearCacheDir(dir) {
+    if (fs.existsSync(dir)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Clear all caches
+ */
+export function clearAllCaches() {
+    const config = getCacheConfig();
+    if (fs.existsSync(config.rootDir)) {
+        fs.rmSync(config.rootDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Get cache statistics for debugging
+ */
+export function getCacheStats() {
+    const config = getCacheConfig();
+    const packagesDir = getFhirPackagesCacheDir();
+    const resourcesDir = getFhirResourcesCacheDir();
+    let packageCount = 0;
+    let resourceCount = 0;
+    try {
+        if (fs.existsSync(packagesDir)) {
+            packageCount = fs.readdirSync(packagesDir).filter(f => fs.statSync(path.join(packagesDir, f)).isDirectory()).length;
+        }
+    }
+    catch { /* ignore */ }
+    try {
+        if (fs.existsSync(resourcesDir)) {
+            resourceCount = fs.readdirSync(resourcesDir).filter(f => f.endsWith('.json')).length;
+        }
+    }
+    catch { /* ignore */ }
+    return {
+        rootDir: config.rootDir,
+        mode: config.mode,
+        packagesDir,
+        resourcesDir,
+        packageCount,
+        resourceCount,
+    };
+}