@atomic-ehr/codegen 0.0.18 → 0.0.19-canary.20260917110212.f40edba

package/README.md

@@ -113,6 +113,58 @@ yarn add @atomic-ehr/codegen
     - `bun run generate-types.ts`
     - `pnpm exec tsx generate-types.ts`
 
+Alternatively, drive the same pipeline from a JSON config file, with no script at all:
+
+```json
+{
+    "version": 1,
+    "builders": [
+        {
+            "name": "core",
+            "fromPackages": [{ "name": "hl7.fhir.r4.core", "version": "4.0.1" }],
+            "typescript": {},
+            "outputTo": "./fhir-types"
+        }
+    ]
+}
+```
+
+```bash
+atomic-codegen generate --config ./codegen.json            # run every builder
+atomic-codegen generate --config ./codegen.json --dry-run  # print the plan without generating
+```
+
+Relative paths resolve against the config file's directory, unknown keys are rejected with the full list of problems, and `outputTo` is removed before generation by default (set `"cleanOutput": false` to keep it). A config may hold several builders: each maps to one `APIBuilder` pipeline (`fromPackages`/`fromPackageRefs`/`localTgzPackages`/`localStructureDefinitions` inputs, `typeSchema` transformations, and `typescript`/`python`/`csharp`/`introspection` generators — see `GenerateConfigBuilder` in `src/api/generate-config.ts`). A failed builder does not stop the others, and the run exits non-zero if any failed.
+
+The JSON `typescript` options also accept `moduleSpecifierStyle` (`"extensionless"` or `"node-esm"`) and `terminology`. For Node ESM imports and terminology output restricted to selected packages, replace `"typescript": {}` with:
+
+```json
+"typescript": {
+    "moduleSpecifierStyle": "node-esm",
+    "terminology": {
+        "enabled": true,
+        "packages": ["hl7.fhir.r4.core@4.0.1"],
+        "packageVerification": {
+            "hl7.fhir.r4.core@4.0.1": "registry-integrity"
+        }
+    }
+}
+```
+
+All terminology fields are optional. When supplied, `enabled` must be a boolean, `packages` must be an array of strings, and `packageVerification` must contain string values. Unknown nested keys and invalid values are reported with their full configuration paths.
+
+### Fixing defective packages
+
+Real FHIR packages ship defects — missing dependencies, typo'd names and canonicals, bindings to unavailable ValueSets, incomplete CodeSystems. Fixes are declared, not hand-coded:
+
+- **Canonical exclusions** — drop a known-broken canonical at the package index, before codegen sees it: `canonicalManager: { patches: { indexEntry: [excludeCanonical({ package, url, reason })] } }`. Codegen ships `builtinPatches` (`src/api/builtin-patches.ts` — generation-breaking content in HL7's own packages, e.g. `hl7.fhir.r5.core` profiles that break R4-compatible generation); they apply to every loader the builder constructs, on top of your own patches, and `builtinPatches: false` is the explicit opt-out. Index exclusion removes the canonical from resolution too, so exclude whole derivation chains together — and it is applied at scan time, so drop the loader cache after changing the list. A hand-built CanonicalManager owns its wiring: apply `builtinPatches.indexEntry` explicitly (see the ccda example).
+- **Custom patches** — per-phase handlers built from the helpers on the `@atomic-ehr/fhir-canonical-manager/patch` subpath (`ensureDependency`, `renamePackage`, `replaceText`, `ensureCodes`, scoped by `inPackage`/`inResource`), passed as `new APIBuilder({ canonicalManager: { patches: {...} } })`. In the CLI config, `"options": { "forceDependencies": {...} }` pins declared dependency versions across the closure.
+- **Broken package index** — `canonicalManager: { packageIndex: "recover" }` heals a corrupt `.index.json` by falling back to a directory scan (always with a warning); `"regenerate"` ignores the shipped index entirely.
+
+Loader settings (`registry`, `packageIndex`, `dropCache`, `patches`) live under the builder's `canonicalManager` option — they configure the CanonicalManager package loader, not the generator. The old flat options are deprecated and warn.
+
+Applied fixes surface in the generation report's "Input fixes" section.
+
 ### Usage Examples
 
 See the [examples/](examples/) directory for working demonstrations:
@@ -157,6 +209,12 @@ const builder = new APIBuilder()
         generateProfile?: boolean,
         withDebugComment?: boolean,
         openResourceTypeSet?: boolean,
+        terminology?: {
+            enabled: true,
+            packageVerification: {
+                "hl7.fhir.r4.core@4.0.1": "registry-integrity",
+            },
+        },
     })
     .python({                                   // Python generator
         client?: "fhirpy" | "none",            // client integration (default: fhirpy)
@@ -204,6 +262,10 @@ Each language generator accepts its own option object. All options are optional;
 | `sliceGetterDefault` | `"flat" \| "raw"` | `"flat"` | Default return shape for generated slice getters (`flat` strips discriminators, `raw` returns the full FHIR element). |
 | `lineWidth` | `number` | `120` | Maximum line width before wrapping. |
 | `withDebugComment` | `boolean` | `false` | Emit comments tracing each generated type back to its source schema. |
+| `terminology.enabled` | `boolean` | `false` | Emit a `terminology.ts` module for every package in the resolved closure. |
+| `terminology.packageVerification` | `Record<string, string>` | `{}` | Map package references such as `hl7.fhir.r4.core@4.0.1` to a closure verification state (`registry-integrity`, `unverifiable`, ...). Absent entries record `not-recorded`. |
+
+When terminology generation is enabled, each exported symbol includes its canonical identity, source package and version, declared content mode, and verification state. Only CodeSystems declaring `content: "complete"` emit code unions and display maps. ValueSet expansions are never promoted to constants, and an `unverifiable` package emits identity and provenance without concept content.
 
 **Python** — `.python({ ... })`
 
@@ -441,6 +503,15 @@ Templates enable flexible code generation for any language or format (Go, Rust,
 
 When generating TypeScript with `generateProfile: true`, the generator creates profile wrapper classes that provide a fluent API for working with FHIR profiles. These classes handle complex profile constraints like slicing and extensions automatically.
 
+Resource profile classes expose `static readonly resourceType` alongside `canonicalUrl`, `from()` and `createResource()`. A generic FHIR client can use the class itself as a structural descriptor. The resource type comes from the resolved snapshot base; Extension and datatype profile classes do not expose `resourceType`.
+
+```typescript
+import { observation_bodyweightProfile } from "./profiles/Observation_observation_bodyweight";
+
+observation_bodyweightProfile.resourceType; // "Observation"
+observation_bodyweightProfile.canonicalUrl; // "http://hl7.org/fhir/StructureDefinition/bodyweight"
+```
+
 ```typescript
 import { observation_bpProfile as bpProfile } from "./profiles/Observation_observation_bp";
 

package/assets/api/writer-generator/python/profile_helpers.py

@@ -417,6 +417,20 @@ def validate_fixed_value(res: object, profile_name: str, field: str, expected: o
     )
 
 
+def validate_pattern_value(res: object, profile_name: str, field: str, expected: object) -> list[str]:
+    """Containment constraint for a field that may be absent: absence is
+    ``validate_required``'s concern, so an absent field passes; a present one
+    must structurally contain ``expected``."""
+    actual = _get_field(res, field)
+    if actual is None:
+        return []
+    return (
+        []
+        if matches_value(actual, expected)
+        else [f"{profile_name}: field '{field}' does not match expected pattern"]
+    )
+
+
 def validate_slice_cardinality(
     res: object,
     profile_name: str,
@@ -451,9 +465,15 @@ def validate_slice_fields(
     match: Mapping[str, Any],
     slice_name: str,
     required_fields: Sequence[str],
+    choice_groups: Sequence[Sequence[str]] = (),
 ) -> list[str]:
     """Validates required fields within matched slice elements. For each array
-    item matching the discriminator, checks that the listed fields are present."""
+    item matching the discriminator, checks that the listed fields are present.
+
+    ``choice_groups`` carries the required choice elements of the slice: each
+    group lists the typed variants a single ``value[x]``-style element may take,
+    and is satisfied by any one of them. E.g. ``[["valueCoding"]]`` for a slice
+    whose ``value[x]`` is required and narrowed to Coding."""
     items = _get_field(res, field) or []
     if not isinstance(items, Iterable):
         items = []
@@ -464,6 +484,14 @@ def validate_slice_fields(
         for rf in required_fields:
             if _get_field(item, rf) is None:
                 errors.append(f"{profile_name}.{field}[{slice_name}].{rf} is required")
+        for group in choice_groups:
+            if any(_get_field(item, variant) is not None for variant in group):
+                continue
+            errors.append(
+                f"{profile_name}.{field}[{slice_name}].{group[0]} is required"
+                if len(group) == 1
+                else f"{profile_name}.{field}[{slice_name}]: at least one of {', '.join(group)} is required"
+            )
     return errors
 
 

package/assets/api/writer-generator/typescript/profile-helpers.ts

@@ -369,13 +369,59 @@ export const validateExcluded = (res: object, profileName: string, field: string
         : [];
 };
 
-/** Checks that `field` structurally contains the expected fixed value. */
-export const validateFixedValue = (res: object, profileName: string, field: string, expected: unknown): string[] => {
-    return matchesValue((res as Record<string, unknown>)[field], expected)
+/**
+ * Shared body for the `fixed[x]`/`pattern[x]` checks, keeping FHIR's two array
+ * rules apart:
+ *
+ * - Across repetitions: a constraint declared on a repeating element applies to
+ *   all repetitions, so every one of them must match and the element must
+ *   actually be an array.
+ * - Inside one value: arrays nested in the constraint keep `matchesValue`'s
+ *   "each constraint entry matches at least one instance entry" rule.
+ */
+const matchesConstrainedValue = (value: unknown, expected: unknown, repeating: boolean): boolean =>
+    repeating
+        ? Array.isArray(value) && value.length > 0 && value.every((item) => matchesValue(item, expected))
+        : !Array.isArray(value) && matchesValue(value, expected);
+
+/**
+ * Checks that a present `field` structurally contains the expected fixed value.
+ * Absence passes — `fixed[x]` applies "if present", so a missing element is
+ * `validateRequired`'s concern. Pass `repeating` for an element with max > 1.
+ */
+export const validateFixedValue = (
+    res: object,
+    profileName: string,
+    field: string,
+    expected: unknown,
+    repeating = false,
+): string[] => {
+    const value = (res as Record<string, unknown>)[field];
+    if (value === undefined || value === null) return [];
+    return matchesConstrainedValue(value, expected, repeating)
         ? []
         : [`${profileName}: field '${field}' does not match expected fixed value`];
 };
 
+/**
+ * Containment constraint for a field that may be absent: absence is
+ * `validateRequired`'s concern, so an absent field passes; a present one must
+ * structurally contain `expected` — every repetition, when `repeating`.
+ */
+export const validatePatternValue = (
+    res: object,
+    profileName: string,
+    field: string,
+    expected: unknown,
+    repeating = false,
+): string[] => {
+    const value = (res as Record<string, unknown>)[field];
+    if (value === undefined || value === null) return [];
+    return matchesConstrainedValue(value, expected, repeating)
+        ? []
+        : [`${profileName}: field '${field}' does not match expected pattern`];
+};
+
 /**
  * Checks that the number of array elements matching `match` (a slice
  * discriminator) falls within [`min`, `max`].  Pass `max = 0` for unbounded.
@@ -404,6 +450,11 @@ export const validateSliceCardinality = (
 /**
  * Validate required fields within matched slice elements.
  * For each array item matching the discriminator, checks that the listed fields are present.
+ *
+ * `choiceGroups` carries the required choice elements of the slice: each group
+ * lists the typed variants a single `value[x]`-style element may take, and is
+ * satisfied by any one of them. E.g. `[["valueCodeableConcept"]]` for a slice
+ * whose `value[x]` is required and narrowed to CodeableConcept.
  */
 export const validateSliceFields = (
     res: object,
@@ -412,16 +463,27 @@ export const validateSliceFields = (
     match: Record<string, unknown>,
     sliceName: string,
     requiredFields: string[],
+    choiceGroups: string[][] = [],
 ): string[] => {
     const items = (res as Record<string, unknown>)[field] as unknown[] | undefined;
     const errors: string[] = [];
+    const isPresent = (obj: Record<string, unknown>, key: string): boolean =>
+        obj[key] !== undefined && obj[key] !== null;
     for (const item of (items ?? []).filter((item) => matchesValue(item, match))) {
         const obj = item as Record<string, unknown>;
         for (const rf of requiredFields) {
-            if (obj[rf] === undefined || obj[rf] === null) {
+            if (!isPresent(obj, rf)) {
                 errors.push(`${profileName}.${field}[${sliceName}].${rf} is required`);
             }
         }
+        for (const group of choiceGroups) {
+            if (group.some((variant) => isPresent(obj, variant))) continue;
+            errors.push(
+                group.length === 1
+                    ? `${profileName}.${field}[${sliceName}].${group[0]} is required`
+                    : `${profileName}.${field}[${sliceName}]: at least one of ${group.join(", ")} is required`,
+            );
+        }
     }
     return errors;
 };