Merge pull request #176 from atomic-ehr/feat/phase1-patch-helpers

API/TypeSchema/CLI: declarative package-defect handling with presets (#128)

Author: ryukzak

CLAUDE.md

@@ -160,6 +160,7 @@ Reference example: `examples/typescript-r4-us-core/profile-r4-bodyweight.test.ts
 - Handles profiles and extensions (US Core in development)
 - Caches parsed schemas for performance
 - Multi-package dependency resolution via Canonical Manager
+- Package defects are fixed declaratively at the loader: `canonicalManager.patches` repairs raw package data and `excludeCanonical` drops known-broken canonicals at the index (helpers from `@atomic-ehr/fhir-canonical-manager/patch`; shipped `builtinPatches` in `src/api/builtin-patches.ts` apply to every builder-constructed loader unless `builtinPatches: false`) — never add ad-hoc workarounds in transformer code
 
 ### TypeSchema Format
 - Intermediate representation between FHIR and target languages

README.md

@@ -153,6 +153,18 @@ The JSON `typescript` options also accept `moduleSpecifierStyle` (`"extensionles
 
 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:

bun.lock

@@ -1,61 +1,50 @@
 // Run this script using Bun CLI with:
 // bun run scripts/generate-fhir-types.ts
 
-import { CanonicalManager, type PreprocessContext } from "@atomic-ehr/fhir-canonical-manager";
+import { CanonicalManager } from "@atomic-ehr/fhir-canonical-manager";
+import { ensureCodes, inPackage, inResource, replaceText } from "@atomic-ehr/fhir-canonical-manager/patch";
 import { registerFromManager } from "@root/typeschema/register";
 import { APIBuilder, prettyReport } from "../../../src/api/builder";
-
-const preprocessPackage = (ctx: PreprocessContext): PreprocessContext => {
-    if (ctx.kind !== "resource") return ctx;
-    if (ctx.package.name === "hl7.cda.uv.core") {
-        let str = JSON.stringify(ctx.resource);
-        str = str.replaceAll(
-            "http://hl7.org/cda/stds/core/StructureDefinition/IVL_TS",
-            "http://hl7.org/cda/stds/core/StructureDefinition/IVL-TS",
-        );
-        return { ...ctx, resource: JSON.parse(str) };
-    }
-    // CarePlanAct profile binds moodCode to an external NLM ValueSet that
-    // isn't available in any loaded package. Reuse the base Act binding.
-    if (ctx.package.name === "hl7.cda.us.ccda") {
-        const res = ctx.resource as { url?: string };
-        if (res.url === "http://hl7.org/cda/us/ccda/StructureDefinition/CarePlanAct") {
-            let str = JSON.stringify(ctx.resource);
-            str = str.replaceAll(
-                "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1267.37",
-                "http://terminology.hl7.org/ValueSet/v3-xDocumentActMood",
-            );
-            return { ...ctx, resource: JSON.parse(str) };
-        }
-    }
-    // The bundle-type CodeSystem is missing codes "bundle" and
-    // "subscription-notification" used by BatchBundle and
-    // SubscriptionNotificationBundle profiles. Patch all instances since
-    // resolveAny may pick any package's copy of the CodeSystem.
-    const res = ctx.resource as { url?: string; concept?: { code: string }[] };
-    if (res.url === "http://hl7.org/fhir/bundle-type" && res.concept) {
-        const existing = new Set(res.concept.map((c) => c.code));
-        const missing = ["bundle", "subscription-notification"].filter((c) => !existing.has(c));
-        if (missing.length > 0) {
-            return {
-                ...ctx,
-                resource: {
-                    ...ctx.resource,
-                    concept: [...res.concept, ...missing.map((code) => ({ code }))],
-                },
-            };
-        }
-    }
-    return ctx;
-};
+import { builtinPatches } from "../../../src/api/builtin-patches";
 
 if (require.main === module) {
     console.log("📦 Generating CCDA Types...");
 
     const manager = CanonicalManager({
         packages: [],
         workingDir: ".codegen-cache/canonical-manager-cache",
-        preprocessPackage,
+        patches: {
+            // The builder injects builtinPatches only into loaders it constructs itself.
+            // This manager is built by hand (we need the register up front to select the
+            // CDA logical models for promoteLogical), and CM patches are constructor-time
+            // configuration that cannot be attached afterwards — so the shipped input
+            // fixes are applied explicitly here.
+            indexEntry: builtinPatches.indexEntry,
+            fhirResource: [
+                // IVL_TS is a typo'd canonical in hl7.cda.uv.core (should be IVL-TS).
+                inPackage("hl7.cda.uv.core", [
+                    replaceText(
+                        "http://hl7.org/cda/stds/core/StructureDefinition/IVL_TS",
+                        "http://hl7.org/cda/stds/core/StructureDefinition/IVL-TS",
+                    ),
+                ]),
+                // CarePlanAct binds moodCode to an external NLM ValueSet absent from every loaded
+                // package; reuse the base Act binding.
+                inPackage("hl7.cda.us.ccda", [
+                    inResource("http://hl7.org/cda/us/ccda/StructureDefinition/CarePlanAct", [
+                        replaceText(
+                            "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1267.37",
+                            "http://terminology.hl7.org/ValueSet/v3-xDocumentActMood",
+                        ),
+                    ]),
+                ]),
+                // The resolved (R4) bundle-type CodeSystem lacks codes pinned by the R5
+                // bundle profiles; patch every copy (resolveAny may pick any).
+                // "subscription-notification" is a real R5 code; "bundle" is an R5 spec typo
+                // for "batch" — FIXME: repair batch-bundle's patternCode instead (output-changing).
+                ensureCodes("http://hl7.org/fhir/bundle-type", ["bundle", "subscription-notification"]),
+            ],
+        },
     });
 
     // Initialize manager with packages to discover CDA resources

examples/on-the-fly/ccda/generate.ts

@@ -11,8 +11,10 @@ if (require.main === module) {
     console.log("Generating KBV Condition Diagnosis types...");
 
     const builder = new APIBuilder({
-        registry: "https://packages.simplifier.net",
-        ignorePackageIndex: true,
+        canonicalManager: {
+            registry: "https://packages.simplifier.net",
+            packageIndex: "regenerate",
+        },
     })
         .fromPackage("kbv.basis", "1.9.0")
         .throwException()

examples/on-the-fly/kbv-condition-diagnosis/generate.ts

@@ -1,36 +1,19 @@
-import type { PreprocessContext } from "@atomic-ehr/fhir-canonical-manager";
+import { ensureDependency, inPackage } from "@atomic-ehr/fhir-canonical-manager/patch";
 import { APIBuilder, prettyReport } from "../../../src/api/builder";
 
-const preprocessPackage = (ctx: PreprocessContext): PreprocessContext => {
-    if (ctx.kind !== "package") return ctx;
-    const json = ctx.packageJson;
-    const name = json.name as string;
-
-    // de.basisprofil.r4 doesn't declare hl7.fhir.r4.core as a dependency
-    if (name === "de.basisprofil.r4") {
-        const deps = (json.dependencies as Record<string, string>) || {};
-        if (!deps["hl7.fhir.r4.core"]) {
-            return {
-                ...ctx,
-                kind: "package",
-                packageJson: {
-                    ...json,
-                    dependencies: { ...deps, "hl7.fhir.r4.core": "4.0.1" },
-                },
-            };
-        }
-    }
-
-    return ctx;
-};
-
 if (require.main === module) {
     console.log("Generating KBV R4 types...");
 
     const builder = new APIBuilder({
-        preprocessPackage,
-        registry: "https://packages.simplifier.net",
-        ignorePackageIndex: true,
+        canonicalManager: {
+            registry: "https://packages.simplifier.net",
+            // de.basisprofil.r4 ships a broken .index.json; heal it with a directory scan.
+            packageIndex: "recover",
+            // de.basisprofil.r4 references core types without declaring hl7.fhir.r4.core.
+            patches: {
+                packageJson: [inPackage("de.basisprofil.r4", [ensureDependency({ "hl7.fhir.r4.core": "4.0.1" })])],
+            },
+        },
     })
         .fromPackage("kbv.ita.for", "1.3.1")
         .fromPackage("de.basisprofil.r4", "1.6.0-ballot2")

examples/on-the-fly/kbv-r4/generate.ts

@@ -1,77 +1,40 @@
-import type { PreprocessContext } from "@atomic-ehr/fhir-canonical-manager";
+import { ensureDependency, inResource, renamePackage, replaceText } from "@atomic-ehr/fhir-canonical-manager/patch";
 import { APIBuilder, prettyReport } from "../../../src/api/builder";
 
-// Fix known package name typos (in-memory transformation)
-const packageNameFixes: Record<string, string> = {
-    "simplifier.core.r4.rResources": "simplifier.core.r4.resources",
-};
-
-// Packages that need hl7.fhir.r4.core dependency injected
-const needsCoreDependency = (name: string): boolean => {
-    return (
-        name.startsWith("simplifier.core.r4.") ||
-        name === "simplifier.core.r4" ||
-        name.startsWith("hl7.fhir.no.") ||
-        name.startsWith("ehelse.fhir.no.") ||
-        name.startsWith("nhn.fhir.no.") ||
-        name.startsWith("sfm.")
-    );
-};
-
-const preprocessPackage = (ctx: PreprocessContext): PreprocessContext => {
-    // GdRelatedPerson widens patient reference to include Person, but the
-    // base R4 RelatedPerson.patient only allows Patient. Drop the Person targets.
-    if (ctx.kind === "resource") {
-        const res = ctx.resource as { url?: string };
-        if (res.url === "http://ehelse.no/fhir/StructureDefinition/gd-RelatedPerson") {
-            let str = JSON.stringify(ctx.resource);
-            str = str.replaceAll(
-                "http://hl7.org/fhir/StructureDefinition/Person",
-                "http://hl7.org/fhir/StructureDefinition/Patient",
-            );
-            str = str.replaceAll(
-                "http://hl7.no/fhir/StructureDefinition/no-basis-Person",
-                "http://hl7.org/fhir/StructureDefinition/Patient",
-            );
-            str = str.replaceAll(
-                "http://ehelse.no/fhir/StructureDefinition/gd-Person",
-                "http://hl7.org/fhir/StructureDefinition/Patient",
-            );
-            return { ...ctx, resource: JSON.parse(str) };
-        }
-        return ctx;
-    }
-    let json = ctx.packageJson;
-    const name = json.name as string;
-
-    // Fix package name typos
-    const fixedName = packageNameFixes[name];
-    if (fixedName) {
-        console.log(`Fixed package name: ${name} -> ${fixedName}`);
-        json = { ...json, name: fixedName };
-    }
-
-    // Add missing core dependency to packages that don't properly declare it
-    if (needsCoreDependency(name)) {
-        const deps = (json.dependencies as Record<string, string>) || {};
-        if (!deps["hl7.fhir.r4.core"]) {
-            console.log(`Injecting hl7.fhir.r4.core dependency into ${name}`);
-            json = {
-                ...json,
-                dependencies: { ...deps, "hl7.fhir.r4.core": "4.0.1" },
-            };
-        }
-    }
-
-    return { ...ctx, kind: "package", packageJson: json };
-};
-
 if (require.main === module) {
     console.log("Generating Norge R4 types...");
 
     const builder = new APIBuilder({
-        preprocessPackage,
-        registry: "https://packages.simplifier.net",
+        canonicalManager: {
+            registry: "https://packages.simplifier.net",
+            patches: {
+                packageJson: [
+                    // Many Norge packages reference core types without declaring the dependency;
+                    // make every package (except core itself) depend on core.
+                    ensureDependency({ "hl7.fhir.r4.core": "4.0.1" }),
+                    // Fix known package name typo.
+                    renamePackage("simplifier.core.r4.rResources", "simplifier.core.r4.resources"),
+                ],
+                // gd-RelatedPerson widens patient to include Person, but base R4 RelatedPerson.patient
+                // only allows Patient — narrow the Person targets back to Patient.
+                fhirResource: [
+                    inResource("http://ehelse.no/fhir/StructureDefinition/gd-RelatedPerson", [
+                        replaceText(
+                            "http://hl7.org/fhir/StructureDefinition/Person",
+                            "http://hl7.org/fhir/StructureDefinition/Patient",
+                        ),
+                        replaceText(
+                            "http://hl7.no/fhir/StructureDefinition/no-basis-Person",
+                            "http://hl7.org/fhir/StructureDefinition/Patient",
+                        ),
+                        replaceText(
+                            "http://ehelse.no/fhir/StructureDefinition/gd-Person",
+                            "http://hl7.org/fhir/StructureDefinition/Patient",
+                        ),
+                    ]),
+                ],
+            },
+        },
     })
         .fromPackage("hl7.fhir.r4.core", "4.0.1")
         .fromPackage("ehelse.fhir.no.grunndata", "2.3.5")

examples/on-the-fly/norge-r4/generate.ts

@@ -1,5 +1,6 @@
 import * as Path from "node:path";
 import { fileURLToPath } from "node:url";
+import { excludeCanonical } from "@atomic-ehr/fhir-canonical-manager/patch";
 import { APIBuilder, prettyReport } from "../../src/api";
 
 const __dirname = Path.dirname(fileURLToPath(import.meta.url));
@@ -36,7 +37,28 @@ console.log(prettyReport(localReport));
 if (!localReport.success) process.exit(1);
 
 // 2. Remote .tgz package by URL (.fromPackageRef) — SQL-on-FHIR → ./sql-on-fhir-types
-const sqlReport = await new APIBuilder()
+const sofReport = await new APIBuilder({
+    // Instead of the shipped builtin patches, declare the known-broken R5 canonicals by hand —
+    // this demonstrates (and continuously exercises) the fully manual loader configuration.
+    // Index patches apply at scan time, so a cached closure needs a cache drop to pick them up.
+    builtinPatches: false,
+    canonicalManager: {
+        patches: {
+            indexEntry: [
+                excludeCanonical({
+                    package: { name: "hl7.fhir.r5.core", version: "5.0.0" },
+                    url: "http://hl7.org/fhir/StructureDefinition/shareablecodesystem",
+                    reason: "Broken CodeSystem.concept.concept content (ElementReference).",
+                }),
+                excludeCanonical({
+                    package: { name: "hl7.fhir.r5.core", version: "5.0.0" },
+                    url: "http://hl7.org/fhir/StructureDefinition/publishablecodesystem",
+                    reason: "Uses R5-only base types not available in R4 generation.",
+                }),
+            ],
+        },
+    },
+})
     .throwException()
     .typescript({ withDebugComment: false, generateProfile: false })
     // The IG references R5 core resources (e.g. ViewDefinition's base chain reaches Library)
@@ -55,7 +77,7 @@ const sqlReport = await new APIBuilder()
     .cleanOutput(true)
     .generate();
 
-console.log(prettyReport(sqlReport));
-if (!sqlReport.success) process.exit(1);
+console.log(prettyReport(sofReport));
+if (!sofReport.success) process.exit(1);
 
 console.log("✅ FHIR types generated successfully!");

examples/typescript-custom-packages/generate.ts

@@ -47,7 +47,7 @@
   },
   "homepage": "https://github.com/atomic-ehr/codegen#readme",
   "dependencies": {
-    "@atomic-ehr/fhir-canonical-manager": "0.0.24",
+    "@atomic-ehr/fhir-canonical-manager": "0.0.26",
     "@atomic-ehr/fhirschema": "0.0.14",
     "brace-expansion": "^5.0.9",
     "mustache": "^4.2.0",