babelfhir-ts 1.0.12 → 1.0.13

package/out/generator/index.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 import { generateClass } from './classGenerator';
 import { generateInterfaces } from './interfaceGenerator';
 import { extractPackage, readStructureDefinitionsFromDir, createPackageFromDir, readValueSetCodesFromDir, readValueSetsFromDir } from './packageParser';
-import { fetchStructureDefinitions, parseStructureDefinition, fetchStructureDefinition } from './sdParser';
+import { fetchStructureDefinitions, parseStructureDefinition, fetchStructureDefinition, registerLocalStructureDefinitions, buildFhirChildTypeMap } from './sdParser';
 import { writeInterfaceAndValidatorToFile, mergeFields, alignFields, ensureDirectoryExists, writeToFile, getBaseResource, downloadFile, sanitizeIdentifier, toPascalCase } from './utils';
 import { generateValidateProfileFunction } from './validatorGenerator';
 import { loadExamplesFromPackage, generateTestFile } from './testGenerator';
@@ -55,7 +55,7 @@ export function skeletonQuantity(): Quantity { return { value: randomInt(1,100),
 }
 // Reusable processor for a single StructureDefinition
 async function processStructureDefinition(sd, ctx) {
-    const { outputDir, fhirSourceHint, valueSetCodesMap, valueSets, examplesMap, existingStructureDefinitions, profileIdToName, flags } = ctx;
+    const { outputDir, fhirSourceHint, valueSetCodesMap, valueSets, examplesMap, existingStructureDefinitions, profileIdToName, flags, fhirChildTypeMap } = ctx;
     const rawInterfaceName = sd.name || sd.id || 'UnnamedInterface';
     const interfaceName = toPascalCase(rawInterfaceName);
     let baseResource = sanitizeIdentifier(getBaseResource(sd.baseDefinition));
@@ -72,7 +72,7 @@ async function processStructureDefinition(sd, ctx) {
         return;
     }
     const aligned = alignFields(parsed.newFields, parsed.oldFields);
-    const interfaceResult = generateInterfaces(interfaceName, aligned.alignedNewFields, baseResource, parsed.oldFields, valueSets, sd.type, existingStructureDefinitions);
+    const interfaceResult = generateInterfaces(interfaceName, aligned.alignedNewFields, baseResource, parsed.oldFields, valueSets, sd.type, existingStructureDefinitions, fhirChildTypeMap);
     const interfaceContent = interfaceResult.content;
     // Generate type alias files for external profiled identifiers that don't exist as StructureDefinitions
     for (const [typeName, profileInfo] of interfaceResult.referencedExternalProfiles) {
@@ -200,6 +200,13 @@ export async function generate(fhirSource, outputDir, flags) {
     }
     console.log(`Fetched ${structureDefinitions.length} StructureDefinitions.`);
     ensureDirectoryExists(outputDir);
+    // Precompute child type map for common core datatypes (best effort; silent on failures)
+    let fhirChildTypeMap = new Map();
+    try {
+        const coreTypes = ['Identifier', 'CodeableConcept', 'Coding', 'Reference', 'Period', 'HumanName', 'Address'];
+        fhirChildTypeMap = await buildFhirChildTypeMap(coreTypes, 'R4');
+    }
+    catch { /* non-fatal */ }
     // Build set of existing StructureDefinition names to avoid generating type aliases for them
     const existingStructureDefinitions = new Set();
     const profileIdToName = new Map(); // Map from profile ID to interface name
@@ -216,7 +223,7 @@ export async function generate(fhirSource, outputDir, flags) {
     }
     const examples = loadExamplesFromPackage(fhirSource);
     for (const sd of structureDefinitions) {
-        await processStructureDefinition(sd, { outputDir, fhirSourceHint: fhirSource, valueSetCodesMap, valueSets, examplesMap: examples, existingStructureDefinitions, profileIdToName, flags });
+        await processStructureDefinition(sd, { outputDir, fhirSourceHint: fhirSource, valueSetCodesMap, valueSets, examplesMap: examples, existingStructureDefinitions, profileIdToName, flags, fhirChildTypeMap });
     }
 }
 /**
@@ -237,9 +244,9 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
         const outputDir = path.join(extractedRoot, 'generated');
         ensureDirectoryExists(outputDir);
         // Generate TypeScript files for ValueSets inside the embedded package
+        let didGenerateValueSets = false;
         if (valueSets.size > 0) {
             const valueSetOutputDir = path.join(outputDir, 'valuesets');
-            ensureDirectoryExists(valueSetOutputDir);
             let generatedValueSetCount = 0;
             let skippedEmptyCount = 0;
             for (const valueSet of valueSets.values()) {
@@ -248,6 +255,10 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
                     continue;
                 }
                 try {
+                    // Only create directory when we actually have files to write
+                    if (generatedValueSetCount === 0) {
+                        ensureDirectoryExists(valueSetOutputDir);
+                    }
                     const { filename, content } = generateValueSetTypeScript(valueSet);
                     fs.writeFileSync(path.join(valueSetOutputDir, filename), content, 'utf-8');
                     generatedValueSetCount++;
@@ -260,9 +271,29 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
                 const registryContent = generateValueSetRegistry(valueSets);
                 fs.writeFileSync(path.join(valueSetOutputDir, 'index.ts'), registryContent, 'utf-8');
                 console.log(`Generated ${generatedValueSetCount} ValueSet files (skipped ${skippedEmptyCount} empty ValueSets) in ${valueSetOutputDir}`);
+                didGenerateValueSets = true;
             }
-            else if (skippedEmptyCount > 0) {
-                console.log(`Skipped ${skippedEmptyCount} empty ValueSets (no files generated)`);
+            else {
+                if (skippedEmptyCount > 0) {
+                    console.log(`Skipped ${skippedEmptyCount} empty ValueSets (no files generated)`);
+                }
+            }
+        }
+        // Ensure no stale valuesets directory remains if we didn't generate any files
+        if (!didGenerateValueSets) {
+            const vdir = path.join(path.join(extractedRoot, 'generated'), 'valuesets');
+            try {
+                if (fs.existsSync(vdir)) {
+                    fs.rmSync(vdir, { recursive: true, force: true });
+                    if (process.env.DEBUG_FHIR_GEN === 'true') {
+                        console.debug(`Removed stale ValueSets directory: ${vdir}`);
+                    }
+                }
+            }
+            catch (e) {
+                if (process.env.DEBUG_FHIR_GEN === 'true') {
+                    console.warn(`Failed to remove stale ValueSets directory ${vdir}: ${e.message}`);
+                }
             }
         }
         // Build set of existing StructureDefinition names
@@ -278,6 +309,8 @@ export async function generateIntoPackage(packageArchivePath, outArchivePath, fl
                 }
             }
         }
+        // Register all local StructureDefinitions for resolution before HTTP fetches
+        registerLocalStructureDefinitions(structureDefinitions);
         const examples = loadExamplesFromPackage(extractedRoot);
         for (const sd of structureDefinitions) {
             await processStructureDefinition(sd, { outputDir, fhirSourceHint: '', valueSetCodesMap, valueSets, examplesMap: examples, existingStructureDefinitions, profileIdToName, flags });
@@ -338,7 +371,6 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
     console.log(`Loaded ${valueSets.size} ValueSets from ${inputDir} (${Array.from(valueSets.values()).filter(vs => vs.isSmall).length} suitable for union types)`);
     // Generate TypeScript files for ValueSets
     const valueSetOutputDir = path.join(outputDir, 'valuesets');
-    ensureDirectoryExists(valueSetOutputDir);
     let generatedValueSetCount = 0;
     let skippedEmptyCount = 0;
     for (const valueSet of valueSets.values()) {
@@ -348,6 +380,10 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
             continue;
         }
         try {
+            // Only create directory when we actually have files to write
+            if (generatedValueSetCount === 0) {
+                ensureDirectoryExists(valueSetOutputDir);
+            }
             const { filename, content } = generateValueSetTypeScript(valueSet);
             const outputPath = path.join(valueSetOutputDir, filename);
             fs.writeFileSync(outputPath, content, 'utf-8');
@@ -364,8 +400,24 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         fs.writeFileSync(registryPath, registryContent, 'utf-8');
         console.log(`Generated ${generatedValueSetCount} ValueSet files (skipped ${skippedEmptyCount} empty ValueSets) in ${valueSetOutputDir}`);
     }
-    else if (skippedEmptyCount > 0) {
-        console.log(`Skipped ${skippedEmptyCount} empty ValueSets (no files generated)`);
+    else {
+        if (skippedEmptyCount > 0) {
+            console.log(`Skipped ${skippedEmptyCount} empty ValueSets (no files generated)`);
+        }
+        // Remove any stale valuesets directory from previous runs
+        try {
+            if (fs.existsSync(valueSetOutputDir)) {
+                fs.rmSync(valueSetOutputDir, { recursive: true, force: true });
+                if (process.env.DEBUG_FHIR_GEN === 'true') {
+                    console.debug(`Removed stale ValueSets directory: ${valueSetOutputDir}`);
+                }
+            }
+        }
+        catch (e) {
+            if (process.env.DEBUG_FHIR_GEN === 'true') {
+                console.warn(`Failed to remove stale ValueSets directory ${valueSetOutputDir}: ${e.message}`);
+            }
+        }
     }
     const entries = fs.readdirSync(inputDir);
     const archives = entries.filter(f => f.endsWith('.tgz') || f.endsWith('.zip'));
@@ -377,11 +429,13 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
     // Build set of existing StructureDefinition names from JSON files
     const existingStructureDefinitions = new Set();
     const profileIdToName = new Map();
+    const localStructureDefinitions = [];
     for (const jf of jsonFiles) {
         try {
             const raw = JSON.parse(fs.readFileSync(path.join(inputDir, jf), 'utf-8'));
             if (typeof raw === 'object' && raw !== null && raw.resourceType === 'StructureDefinition') {
                 const sd = raw;
+                localStructureDefinitions.push(sd); // Collect for local resolution
                 const name = toPascalCase(sd.name || sd.id || '');
                 if (name) {
                     existingStructureDefinitions.add(name);
@@ -394,6 +448,8 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         }
         catch { /* ignore parse errors in pre-scan */ }
     }
+    // Register all local StructureDefinitions for resolution before HTTP fetches
+    registerLocalStructureDefinitions(localStructureDefinitions);
     for (const file of archives) {
         const fullPath = path.join(inputDir, file);
         console.log(`Processing package: ${file}`);
@@ -411,10 +467,6 @@ export async function generateForDirectory(inputDir, outputDir, flags) {
         const full = path.join(inputDir, jf);
         try {
             const raw = JSON.parse(fs.readFileSync(full, 'utf-8'));
-            if (typeof raw !== 'object' || raw === null || raw.resourceType !== 'StructureDefinition') {
-                console.warn(`Skipping non-StructureDefinition JSON: ${jf}`);
-                continue;
-            }
             await processStructureDefinition(raw, { outputDir, fhirSourceHint: full, valueSets, existingStructureDefinitions, profileIdToName, flags });
         }
         catch (err) {

package/out/generator/interfaceGenerator.js

@@ -1,10 +1,10 @@
 import fhirInterfaceNames from "./fhirInterfaces.json";
-import { capitalize, sanitizeIdentifier } from './utils';
+import { capitalize, sanitizeIdentifier, toPascalCase } from './utils';
 import { generateCodeUnionType, getUniformSystem } from './vsParser.js';
 import { logger } from '../logger';
-export function generateInterfaces(interfaceName, newFields, baseResource, baseFields = [], valueSets, resourceType, existingProfiles) {
+export function generateInterfaces(interfaceName, newFields, baseResource, baseFields = [], valueSets, resourceType, existingProfiles, fhirChildTypeMap) {
     const debug = (...args) => { if (process.env.DEBUG_FHIR_GEN === 'true')
-        logger.log('[gen:interfaces]', ...args); };
+        console.log('[gen:interfaces]', ...args); };
     const imports = new Set();
     const customImports = new Set();
     const interfacesRaw = [];
@@ -14,7 +14,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 return (...items) => {
                     for (const item of items) {
                         if (item.includes('Code') && interfaceName.includes('Condition')) {
-                            logger.log('[INTERFACES.PUSH]', { interfaceName, item: item.substring(0, 80), stack: new Error().stack?.split('\n')[2] });
+                            console.log('[INTERFACES.PUSH]', { interfaceName, item: item.substring(0, 80), stack: new Error().stack?.split('\n')[2] });
                         }
                     }
                     return target.push(...items);
@@ -24,7 +24,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 return (...items) => {
                     for (const item of items) {
                         if (item.includes('Code') && interfaceName.includes('Condition')) {
-                            logger.log('[INTERFACES.UNSHIFT]', { interfaceName, item: item.substring(0, 80), stack: new Error().stack?.split('\n')[2] });
+                            console.log('[INTERFACES.UNSHIFT]', { interfaceName, item: item.substring(0, 80), stack: new Error().stack?.split('\n')[2] });
                         }
                     }
                     return target.unshift(...items);
@@ -138,10 +138,15 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             return `CodeableConcept & { coding: Array<{ code: ${codeUnion} }> }`;
         }
     };
-    function processFields(fields, parentInterfaceName, parentFieldType) {
+    function processFields(fields, parentInterfaceName, parentFieldType, isProcessingSlice = false) {
         const interfaceLines = [];
         const emittedLinesByField = new Map();
         const processedFields = new Set();
+        // Context-aware resolver: only use base field metadata for direct children of the base resource.
+        const getBaseFldForContext = (fname, fparts, currentParent) => {
+            const isDirectBaseChild = currentParent === interfaceName && fparts.length === 2 && fparts[0] === baseResource;
+            return isDirectBaseChild ? baseFieldByLastSegment.get(fname) : undefined;
+        };
         const canonicalToTypeName = (name) => {
             if (!name)
                 return name;
@@ -178,11 +183,19 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
         fields.forEach((field) => {
             const fieldParts = field.name.split(".");
             let fieldName = fieldParts[fieldParts.length - 1];
-            if (interfaceName.includes('address') && interfaceName.includes('0_2') && field.name.includes('line')) {
-                logger.log('[FIELD PROCESSING]', { interfaceName, 'field.name': field.name, fieldName, sliceName: field.sliceName });
-            }
             const isRootInterface = parentInterfaceName === interfaceName;
             const isNested = isRootInterface ? fieldParts.length > 1 : fieldParts.length >= 1;
+            // When generating a slice-specific interface, only include direct children
+            // (1 segment deep) and skip deeper nested paths (2+ segments) to avoid
+            // flattening nested structures into the slice interface.
+            if (isProcessingSlice && fieldParts.length > 1) {
+                debug('skipping deeply nested field in slice interface', {
+                    fieldName: field.name,
+                    parentInterfaceName,
+                    depth: fieldParts.length
+                });
+                return;
+            }
             if (field.name.includes('bodySite.extension')) {
                 logger.log('[DEBUG ALL bodySite.extension fields]', {
                     fieldName: field.name,
@@ -226,7 +239,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             // Only apply nested-parent name filtering for deeper nesting (>= 3 segments like Account.coverage.extension).
             // For profiles that extend a base type (e.g., IdentifierEfn extends Identifier), only include direct children
             // (2 segments: Identifier.system) and skip nested paths (4+ segments: Identifier.assigner.identifier.system)
-            if (isNested && fieldParts.length > 2) {
+            if (isNested && fieldParts.length >= 2) {
                 const baseTypeName = fieldParts[0]; // e.g., "Identifier" from "Identifier.assigner.identifier.system"
                 const isExtendingBaseType = baseResource && baseTypeName.toLowerCase() === baseResource.toLowerCase();
                 // Check if this field will create a nested interface (has children in fields)
@@ -234,6 +247,37 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 const shouldKeepForNested = field.mustSupport && hasChildren;
                 // Logical models extending Base should treat 2-segment paths as direct properties, not nested filtering
                 const isLogicalModel = baseResource === 'Base';
+                // For slice-specific interfaces (e.g., SiuAppointmentIdentifier for Appointment.identifier:doctolib),
+                // only include direct children of the slice, not deeply nested descendants like assigner.reference
+                // Detect whether this element is part of a slice by checking its ancestors
+                // and find the depth (number of segments) of the slice root. This ensures
+                // that descendant elements (e.g. assigner.type) are recognized as part of
+                // the slice and can be skipped from the slice-specific interface so that
+                // nested structures remain nested instead of being flattened.
+                let sliceRootDepth = -1;
+                for (let i = fieldParts.length; i >= 1; i--) {
+                    const testPath = fieldParts.slice(0, i).join('.');
+                    // Use the top-level fields list (newFields) when searching for the slice
+                    // definition so nested invocations with relative names can still detect
+                    // the original slice root.
+                    const hasSliceAtDepth = newFields.some(f => f.name === testPath && f.sliceName);
+                    if (hasSliceAtDepth) {
+                        sliceRootDepth = i;
+                        break;
+                    }
+                }
+                const isPartOfSlice = sliceRootDepth > -1 || !!field.sliceName;
+                // If this is part of a slice and we're more than 1 level deep from the slice root, skip it
+                // (We only want direct children of the slice root in the slice-specific interface.)
+                if (isPartOfSlice && sliceRootDepth > 0 && fieldParts.length > sliceRootDepth + 1) {
+                    debug('skipping deeply nested field in slice', {
+                        fieldName: field.name,
+                        sliceRootDepth,
+                        currentDepth: fieldParts.length,
+                        parentInterfaceName
+                    });
+                    return;
+                }
                 if (isExtendingBaseType && !isLogicalModel) {
                     // For profiles extending their base type, only include direct children (exactly 2 segments)
                     // UNLESS the field has mustSupport and children (will create nested interface)
@@ -286,7 +330,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 return;
             }
             if (interfaceName.includes('address') && interfaceName.includes('0_2') && field.name === 'Address.line') {
-                logger.log('[AFTER SKIP CHECK]', { 'field.name': field.name, 'passed skip check': true });
+                console.log('[AFTER SKIP CHECK]', { 'field.name': field.name, 'passed skip check': true });
             }
             if (fieldName === "value[x]")
                 fieldName = "value";
@@ -332,7 +376,8 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             if (isFhirType(field.type))
                 addTypeImport(field.type);
             const conservative = baseFieldByLastSegment.size === 0;
-            let treatAsNested = isNested;
+            // In nested contexts, direct children (single segment) should be treated as properties, not nested backbones
+            let treatAsNested = isNested && !(parentInterfaceName !== interfaceName && fieldParts.length === 1);
             // Don't create nested interfaces for extension slices - they contribute to extension unions
             const fieldPathParts = field.name.split('.');
             const lastPart = fieldPathParts[fieldPathParts.length - 1];
@@ -378,7 +423,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         if (hasChildExtSlices && isPrimitiveType(mappedBase)) {
                             treatAsNested = false;
                             if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
-                                logger.log('[SET treatAsNested = false for line]');
+                                console.log('[SET treatAsNested = false for line]');
                             }
                         }
                         debug('retain nested backbone due to profiled descendant', field.name);
@@ -472,8 +517,9 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 let baseFieldType = baseFieldByLastSegment.get(fieldName)?.type || field.type;
                 // If base type is missing/any/generic BackboneElement and this is a known backbone of the base resource,
                 // use the concrete backbone interface (e.g., DocumentReferenceContent)
+                // Use resourceType (the ultimate FHIR base like "Appointment") not baseResource (which might be a profile like "DoctolibAppointment")
                 if (!baseFieldType || baseFieldType === 'any' || baseFieldType === 'BackboneElement') {
-                    const inferred = inferBackboneType(baseResource, fieldName);
+                    const inferred = inferBackboneType(resourceType || baseResource, fieldName);
                     if (inferred)
                         baseFieldType = inferred;
                 }
@@ -492,10 +538,14 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         nestedFieldsCount: nestedFields.length
                     });
                 }
+                // Check if this nested interface is for a sliced element
+                // (there may be multiple fields at the same path with different sliceNames)
+                const isSlicedElement = fields.some(f => f.name === field.name && f.sliceName);
                 processFields(nestedFields.map((f) => ({
                     ...f,
                     name: f.name.replace(`${field.name}.`, ""),
-                })), nestedInterfaceName, baseFieldType);
+                })), nestedInterfaceName, baseFieldType, isSlicedElement // Pass true if ANY field at this path has a sliceName
+                );
                 let nestedDefined = interfaces.some(i => i.startsWith(`export interface ${nestedInterfaceName}`));
                 if (fieldName === 'answer' && field.mustSupport) {
                     logger.log('[DEBUG answer after processFields]', {
@@ -520,7 +570,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     const aliasTypes = [];
                     for (const sl of extensionSlices) {
                         for (const url of sl.profileUrls || []) {
-                            const alias = sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice');
+                            const alias = toPascalCase(sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice'));
                             // Generate minimal alias interface locally if not present elsewhere
                             if (!generatedAliasTypes.has(alias)) {
                                 interfaces.unshift(`export interface ${alias} extends Extension { url: '${url}' }`);
@@ -576,7 +626,34 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     // Fall through to emit the field with updated cardinality
                     debug('emit base child with changed cardinality', field.name, { baseOptional: baseFld?.isOptional, profileOptional: field.isOptional });
                 }
+                // For nested interfaces that extend a base type (e.g., SiuAppointmentParticipant extends AppointmentParticipant),
+                // if we're only changing cardinality (not type), preserve the base field's type instead of downgrading to primitives
                 const baseFld = baseFieldByLastSegment.get(fieldName);
+                const isOnlyCardinalityChange = baseFld && !nestedDefined &&
+                    (baseFld.isOptional !== field.isOptional || baseFld.isArray !== field.isArray) &&
+                    field.type === baseFld.type && // Type hasn't changed
+                    !field.isProfiled && !field.fixedValue; // No other constraints
+                // For nested interfaces extending FHIR base types, skip fields with no real constraints
+                // (FHIR base types like AppointmentParticipant have rich union types that we want to preserve)
+                const isNestedExtendingFhirBase = parentInterfaceName !== interfaceName && parentFieldType && isFhirType(parentFieldType);
+                // For root interfaces extending other profiles (e.g., SiuAppointment extends DoctolibAppointment),
+                // also skip fields with no constraints (they inherit from the profile chain)
+                const isRootExtendingProfile = parentInterfaceName === interfaceName && baseResource && baseResource !== interfaceName;
+                const hasChildren = fields.some((f) => f.name.startsWith(`${field.name}.`));
+                const hasNoConstraints = baseFld && !nestedDefined && !hasChildren &&
+                    baseFld.isOptional === field.isOptional &&
+                    baseFld.isArray === field.isArray &&
+                    field.type === baseFld.type &&
+                    !field.isProfiled && !field.fixedValue;
+                // Skip fields with NO constraints at all (they inherit perfectly from base)
+                // But DON'T skip fields that only change cardinality - we need to emit those with correct optionality
+                if ((isNestedExtendingFhirBase || isRootExtendingProfile) && hasNoConstraints && !isOnlyCardinalityChange) {
+                    debug('skip field with no constraints - inherit from base', field.name);
+                    return;
+                }
+                // For fields that only change cardinality, we'll emit them but use the base type
+                // (preserving union types, etc.) with the correct optionality marker
+                const useBaseTypeForCardinality = (isNestedExtendingFhirBase || isRootExtendingProfile) && isOnlyCardinalityChange;
                 // Check if this is a primitive field with child extension slices
                 const hasChildExtSlices = fields.some(f => f.name === `${field.name}.extension` && f.sliceName && (f.profileUrls || []).length > 0);
                 const mappedBaseType = mapTypeToTS((baseFld?.type || field.type || 'string'));
@@ -589,16 +666,38 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 // The nested interface is only for the sidecar _field element
                 // Also, for extension fields with slices, the union will be added separately
                 let resolvedType = (nestedDefined && !isPrimitiveWithExtSlices && !isExtensionWithSlices) ? nestedInterfaceName : resolveEffectiveType(field, baseFld);
-                if (!nestedDefined) {
-                    // Prefer explicit backbone interface if resolvable (e.g., EncounterHospitalization)
-                    const inferred = inferBackboneType(baseResource, fieldName);
-                    if (!field.isProfiled && inferred) {
-                        resolvedType = inferred;
+                // For cardinality-only changes, use the base field's type directly to preserve union types, etc.
+                if (useBaseTypeForCardinality && baseFld?.type) {
+                    resolvedType = baseFld.type;
+                    debug('using base type for cardinality-only change', field.name, { baseType: baseFld.type });
+                }
+                else if (!nestedDefined) {
+                    // For direct children of the root resource, prefer explicit backbone inference
+                    if (parentInterfaceName === interfaceName) {
+                        const inferred = inferBackboneType(baseResource, fieldName);
+                        if (!field.isProfiled && inferred) {
+                            resolvedType = inferred;
+                        }
+                        else {
+                            resolvedType = mapTypeToTS(resolvedType);
+                        }
                     }
                     else {
+                        // Nested contexts: do not infer resource-level backbones, just map primitives
                         resolvedType = mapTypeToTS(resolvedType);
                     }
                 }
+                // Ensure CodeableConcept.text remains string (avoid Resource.text Narrative leakage)
+                if (fieldName === 'text' && parentFieldType && sanitizeIdentifier(parentFieldType) === 'CodeableConcept') {
+                    resolvedType = 'string';
+                }
+                // Special-case: Bundle.entry.resource should be FhirResource
+                if (fieldName === 'resource' && (baseResource === 'Bundle' || resourceType === 'Bundle')) {
+                    resolvedType = 'FhirResource';
+                    imports.add('FhirResource');
+                }
+                // Final primitive normalization for nested branch as well
+                resolvedType = mapTypeToTS(resolvedType);
                 // For profiled child elements (Attachment with CustomAttachment profile etc.), prefer the profiled type name directly.
                 if (field.isProfiled && field.type) {
                     resolvedType = canonicalToTypeName(field.type);
@@ -614,7 +713,8 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         resolvedType = sanitized;
                     }
                 }
-                const baseArrFlag = baseFieldByLastSegment.get(fieldName)?.isArray;
+                // Only use base arrayness for direct children of the base resource; nested child fields must rely on their own cardinality
+                const baseArrFlag = getBaseFldForContext(fieldName, fieldParts, parentInterfaceName)?.isArray;
                 // If base arrayness is unknown (failed to fetch base metadata), default to array for known repeating fields
                 // like Account.coverage when emitting the root-level property.
                 const defaultArrayForKnownRepeatsNested = (baseArrFlag === undefined &&
@@ -776,14 +876,14 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     const mustSupportChanged = baseFld && (!baseFld.mustSupport && field.mustSupport);
                     const cardinalityChanged = baseFld && (baseFld.isOptional !== field.isOptional || baseFld.isArray !== field.isArray);
                     if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
-                        logger.log('[PRIMITIVE OVERRIDE CHECK]', { isPrimitive: isPrimitiveType(mapped), hasExtensionSlices, hasIdentifierSlices, mustSupportChanged, cardinalityChanged, willReturn: isPrimitiveType(mapped) && !hasExtensionSlices && !hasIdentifierSlices && !mustSupportChanged && !cardinalityChanged });
+                        console.log('[PRIMITIVE OVERRIDE CHECK]', { isPrimitive: isPrimitiveType(mapped), hasExtensionSlices, hasIdentifierSlices, mustSupportChanged, cardinalityChanged, willReturn: isPrimitiveType(mapped) && !hasExtensionSlices && !hasIdentifierSlices && !mustSupportChanged && !cardinalityChanged });
                     }
                     if (isPrimitiveType(mapped) && !hasExtensionSlices && !hasIdentifierSlices && !mustSupportChanged && !cardinalityChanged) {
                         debug('skip primitive override of base child', field.name, 'mappedType=', mapped);
                         return;
                     }
                     if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
-                        logger.log('[AFTER PRIMITIVE OVERRIDE CHECK - continuing]');
+                        console.log('[AFTER PRIMITIVE OVERRIDE CHECK - continuing]');
                     }
                     // Also check if cardinality changed (optional -> required) - if so, emit for documentation
                     if (!cardinalityChanged && !mustSupportChanged && !isPrimitiveType(mapped) && !hasIdentifierSlices) {
@@ -809,10 +909,11 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     }
                 }
                 // Heuristic: if base field exists and we're about to widen/narrow it improperly, skip emission.
-                const baseField = baseFieldByLastSegment.get(fieldName);
+                const baseField = getBaseFldForContext(fieldName, fieldParts, parentInterfaceName);
                 const enumeratedSkip = new Set(['status', 'gender', 'class', 'category', 'concept', 'entry', 'clinicalStatus', 'verificationStatus']);
                 const mustSupportChanged = baseField && (!baseField.mustSupport && field.mustSupport);
-                if (parentInterfaceName === interfaceName && !field.fixedValue && !mustSupportChanged) {
+                const cardinalityChanged = baseField && (baseField.isOptional !== field.isOptional || baseField.isArray !== field.isArray);
+                if (parentInterfaceName === interfaceName && !field.fixedValue && !mustSupportChanged && !cardinalityChanged) {
                     if (enumeratedSkip.has(fieldName))
                         return;
                     if (baseResource === 'UsageContext' && fieldName === 'code' && field.type === 'string')
@@ -842,7 +943,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     // If new type is primitive (or code -> string) while base is non-primitive, skip to retain richer base definition.
                     const mapped = mapTypeToTS(field.type || 'string');
                     if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
-                        logger.log('[MAPPED TYPE CHECK]', { mapped, isPrimitive: isPrimitiveType(mapped), baseFieldType: baseField.type, baseFieldIsPrimitive: baseField.type ? isPrimitiveType(baseField.type) : 'no baseField.type', hasExtensionSlices, willReturn: isPrimitiveType(mapped) && baseField.type && !isPrimitiveType(baseField.type) && !hasExtensionSlices });
+                        console.log('[MAPPED TYPE CHECK]', { mapped, isPrimitive: isPrimitiveType(mapped), baseFieldType: baseField.type, baseFieldIsPrimitive: baseField.type ? isPrimitiveType(baseField.type) : 'no baseField.type', hasExtensionSlices, willReturn: isPrimitiveType(mapped) && baseField.type && !isPrimitiveType(baseField.type) && !hasExtensionSlices });
                     }
                     if (isPrimitiveType(mapped) && baseField.type && !isPrimitiveType(baseField.type) && !hasExtensionSlices) {
                         return; // rely on inherited definition
@@ -851,7 +952,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     // Additional guard: Sometimes differential loses specific complex type information and we parse as 'any' or 'string'.
                     // If base field exists and is an array but new appears singular primitive, skip overriding to keep array.
                     if (fieldName === 'line') {
-                        logger.log('[ARRAY CHECK 768]', {
+                        console.log('[ARRAY CHECK 768]', {
                             baseFieldIsArray: baseField.isArray,
                             fieldIsArray: field.isArray,
                             fieldType: field.type,
@@ -866,7 +967,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     // Special cases: known enumerated code fields (status, gender, intent, class, category) -> avoid overriding unless fixed or mustSupport changed
                     const mustSupportChanged = baseField.mustSupport !== field.mustSupport && field.mustSupport === true;
                     if (fieldName === 'line') {
-                        logger.log('[ENUM CHECK 772]', {
+                        console.log('[ENUM CHECK 772]', {
                             fieldName,
                             fixedValue: field.fixedValue,
                             mustSupportChanged,
@@ -882,11 +983,11 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         return;
                     if (fieldName === 'beneficiary' && baseField.type === 'Reference')
                         return;
-                    if (['concept', 'entry'].includes(fieldName) && !field.fixedValue)
+                    if (['concept', 'entry', 'content'].includes(fieldName) && !field.fixedValue)
                         return;
                     // Additional guard: avoid overriding well-known enum/union fields with raw string
                     // Even if mustSupport changes, we should inherit the base enum type, not override with string
-                    if (['gender', 'status', 'intent', 'lifecycleStatus', 'clinicalStatus', 'verificationStatus'].includes(fieldName) && isPrimitiveType(mapped)) {
+                    if (['gender', 'status', 'intent', 'lifecycleStatus', 'clinicalStatus', 'verificationStatus', 'content'].includes(fieldName) && isPrimitiveType(mapped)) {
                         return;
                     }
                     // Skip if identical to base (same type, array flag, optionality, AND mustSupport)
@@ -894,7 +995,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         const mappedType = mapTypeToTS(field.type || 'string');
                         const mustSupportSame = baseField.mustSupport === field.mustSupport;
                         if (fieldName === 'line') {
-                            logger.log('[IDENTICAL CHECK 796]', {
+                            console.log('[IDENTICAL CHECK 796]', {
                                 baseFieldType: baseField.type,
                                 fieldType: field.type,
                                 mappedType,
@@ -923,7 +1024,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         }
                     }
                 }
-                const baseFld = baseFieldByLastSegment.get(fieldName);
+                const baseFld = getBaseFldForContext(fieldName, fieldParts, parentInterfaceName);
                 let fieldType = resolveEffectiveType(field, baseFld);
                 // Map raw FHIR primitive codes (e.g., dateTime) to TS primitives unless the field is explicitly profiled.
                 if (!field.isProfiled) {
@@ -937,9 +1038,21 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                             fieldType = mapTypeToTS(fieldType);
                     }
                     else {
-                        fieldType = mapTypeToTS(fieldType);
+                        // In nested contexts where parent is a known FHIR type, prefer known child types to avoid degrading to primitives
+                        if (parentFieldType && isFhirType(parentFieldType)) {
+                            const inferredChild = inferFhirChildType(parentFieldType, fieldName);
+                            fieldType = inferredChild ? inferredChild : mapTypeToTS(fieldType);
+                        }
+                        else {
+                            fieldType = mapTypeToTS(fieldType);
+                        }
                     }
                 }
+                // Special-case: Bundle.entry.resource should be FhirResource, not Resource
+                if (fieldName === 'resource' && (baseResource === 'Bundle' || resourceType === 'Bundle')) {
+                    fieldType = 'FhirResource';
+                    imports.add('FhirResource');
+                }
                 // Normalize canonical URLs to local type names
                 if (!isPrimitiveType(fieldType) && !isFhirType(fieldType)) {
                     fieldType = canonicalToTypeName(fieldType);
@@ -951,7 +1064,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         const aliasTypes = [];
                         for (const sl of samePathSlices) {
                             for (const url of sl.profileUrls || []) {
-                                const alias = sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice');
+                                const alias = toPascalCase(sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice'));
                                 if (!generatedAliasTypes.has(alias)) {
                                     interfaces.unshift(`export interface ${alias} extends Extension { url: '${url}' }`);
                                     generatedAliasTypes.add(alias);
@@ -1007,22 +1120,22 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 // If this field has extension slices on its child '.extension', synthesize a nested interface
                 // BUT: if the current field IS "extension" itself, skip this - extension slices are handled elsewhere
                 if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
-                    logger.log('[BEFORE CHILD EXT CHECK]', { 'field.name': field.name, fieldName, 'reached this point': true });
+                    console.log('[BEFORE CHILD EXT CHECK]', { 'field.name': field.name, fieldName, 'reached this point': true });
                 }
                 const childExtensionSlices = fields.filter(f => f.name === `${field.name}.extension` && f.sliceName && (f.profileUrls || []).length > 0);
                 if (interfaceName.includes('address') && interfaceName.includes('0_2') && field.name === 'Address.line') {
-                    logger.log('[CHILD EXT CHECK - Address.line]', { 'field.name': field.name, childExtensionSlicesLength: childExtensionSlices.length, fieldName, filterCheck: fields.filter(f => f.name === `${field.name}.extension` && f.sliceName).map(f => ({ name: f.name, sliceName: f.sliceName, profileUrls: f.profileUrls })) });
+                    console.log('[CHILD EXT CHECK - Address.line]', { 'field.name': field.name, childExtensionSlicesLength: childExtensionSlices.length, fieldName, filterCheck: fields.filter(f => f.name === `${field.name}.extension` && f.sliceName).map(f => ({ name: f.name, sliceName: f.sliceName, profileUrls: f.profileUrls })) });
                 }
                 if (childExtensionSlices.length > 0 && fieldName !== 'extension') {
                     if (interfaceName.includes('address') && fieldName === 'line') {
-                        logger.log('[CREATING SIDECAR]', { interfaceName, parentInterfaceName, fieldName, childExtensionSlicesLength: childExtensionSlices.length });
+                        console.log('[CREATING SIDECAR]', { interfaceName, parentInterfaceName, fieldName, childExtensionSlicesLength: childExtensionSlices.length });
                     }
                     const nestedInterfaceName = `${parentInterfaceName}${capitalize(fieldName)}`;
                     // Build union members and alias types
                     const aliasTypes = [];
                     for (const sl of childExtensionSlices) {
                         for (const url of sl.profileUrls || []) {
-                            const alias = sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice');
+                            const alias = toPascalCase(sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice'));
                             if (!generatedAliasTypes.has(alias)) {
                                 interfaces.unshift(`export interface ${alias} extends Extension { url: '${url}' }`);
                                 generatedAliasTypes.add(alias);
@@ -1035,7 +1148,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                     const union = ['Extension', ...aliasTypes].join(' | ');
                     const extLine = `extension?: (${union})[];`;
                     // Determine parent type to extend
-                    const baseFld2 = baseFieldByLastSegment.get(fieldName);
+                    const baseFld2 = getBaseFldForContext(fieldName, fieldParts, parentInterfaceName);
                     let parentT = resolveEffectiveType(field, baseFld2);
                     if (!field.isProfiled)
                         parentT = mapTypeToTS(parentT || 'string');
@@ -1068,7 +1181,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                         // For root interfaces, check baseResource; for nested, check parentFieldType
                         const effectiveParentType = parentFieldType || baseResource;
                         if (fieldName === 'line' || fieldName === 'prefix') {
-                            logger.log('[SIDECAR DEBUG]', {
+                            console.log('[SIDECAR DEBUG]', {
                                 profileName: interfaceName,
                                 parentInterfaceName,
                                 fieldName,
@@ -1089,7 +1202,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                             }
                         }
                         if (fieldName === 'line' || fieldName === 'prefix') {
-                            logger.log('[SIDECAR RESULT]', { parentInterfaceName, fieldName, finalSidecarIsArray: sidecarIsArray });
+                            console.log('[SIDECAR RESULT]', { parentInterfaceName, fieldName, finalSidecarIsArray: sidecarIsArray });
                         }
                         const sidecarType = sidecarIsArray ? `${elementIface}[]` : elementIface;
                         // Prefer optional sidecar by default to match base optionality and avoid duplicate required/optional declarations
@@ -1162,7 +1275,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 // Preserve arrayness from base when known; if base metadata is missing and field name is a known repeating element (e.g., 'coverage' on Account),
                 // default to array to avoid incorrect narrowing.
                 // Skip adding [] if fieldType already contains array syntax (e.g., from identifier/extension union types)
-                const baseArrKnown = baseFieldByLastSegment.get(fieldName)?.isArray;
+                const baseArrKnown = getBaseFldForContext(fieldName, fieldParts, parentInterfaceName)?.isArray;
                 const defaultArrayForKnownRepeats = (!isNested && fieldName === 'coverage' && baseResource === 'Account');
                 const alreadyHasArraySyntax = fieldType.endsWith('[]');
                 // For nested contexts (or when extending FHIR types), check if the parent type is a known FHIR type with known field cardinality
@@ -1174,6 +1287,8 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
                 const isArrayOut = alreadyHasArraySyntax ? false : ((baseArrKnown !== undefined) ? baseArrKnown :
                     (fhirParentArrayKnown !== undefined) ? fhirParentArrayKnown :
                         (field.isArray || defaultArrayForKnownRepeats));
+                // Final primitive normalization to ensure uri/url/etc are mapped to string
+                fieldType = mapTypeToTS(fieldType);
                 const line = `${fieldName}${field.isOptional ? '?' : ''}: ${fieldType}${isArrayOut ? '[]' : ''};`;
                 debug(`About to check line for ${field.name}: fieldType=${fieldType}, line="${line}"`);
                 if (parentInterfaceName === interfaceName && writtenLines.has(line)) {
@@ -1308,7 +1423,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
     }
     // lines preserved; accidental duplicates removed
     function isFhirType(type) {
-        return fhirInterfaceNames.includes(type);
+        return type === 'FhirResource' || fhirInterfaceNames.includes(type);
     }
     // Returns true if a field on a known FHIR type is an array
     function isFhirFieldArray(parentType, fieldName) {
@@ -1338,6 +1453,69 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             return undefined; // unknown parent type
         return arrayFields.has(fieldName);
     }
+    // Returns the known FHIR child type for a given parent FHIR type and field name, to preserve correct types in nested contexts
+    function inferFhirChildType(parentType, fieldName) {
+        // Prefer data-driven map if available
+        const parentSan = sanitizeIdentifier(parentType);
+        const fromMap = fhirChildTypeMap?.get(parentSan)?.get(fieldName)?.type;
+        if (fromMap) {
+            // Normalize primitives like uri/url/canonical to string
+            return mapTypeToTS(fromMap);
+        }
+        // Fallback minimal hardcoded hints for common types
+        const map = {
+            Identifier: {
+                type: 'CodeableConcept',
+                period: 'Period',
+                assigner: 'Reference',
+                system: 'string',
+                value: 'string',
+                use: 'string',
+            },
+            Reference: {
+                identifier: 'Identifier',
+                type: 'string',
+                reference: 'string',
+                display: 'string',
+            },
+            CodeableConcept: {
+                coding: 'Coding',
+                text: 'string',
+            },
+            Coding: {
+                system: 'string',
+                version: 'string',
+                code: 'string',
+                display: 'string',
+                userSelected: 'boolean',
+            },
+            Period: {
+                start: 'string',
+                end: 'string',
+            },
+            HumanName: {
+                use: 'string',
+                text: 'string',
+                family: 'string',
+                given: 'string',
+                prefix: 'string',
+                suffix: 'string',
+            },
+            Address: {
+                use: 'string',
+                type: 'string',
+                text: 'string',
+                city: 'string',
+                district: 'string',
+                state: 'string',
+                postalCode: 'string',
+                country: 'string',
+                period: 'Period',
+                line: 'string',
+            },
+        };
+        return map[parentSan]?.[fieldName];
+    }
     if (baseResource && !isPrimitiveType(baseResource) && sanitizeIdentifier(baseResource) !== 'Base') {
         const sanitizedBase = sanitizeIdentifier(baseResource);
         // Skip custom German coverage base pseudo-types that we cannot resolve
@@ -1384,7 +1562,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             const containerPath = f.name.replace(/\.extension$/, '');
             const arr = byContainer.get(containerPath) || [];
             for (const url of f.profileUrls) {
-                const alias = sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice');
+                const alias = toPascalCase(sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice'));
                 arr.push({ url, alias });
             }
             byContainer.set(containerPath, arr);
@@ -1641,7 +1819,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             const aliases = [];
             for (const sl of rootExtSlices) {
                 for (const url of sl.profileUrls || []) {
-                    const alias = sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice');
+                    const alias = toPascalCase(sanitizeIdentifier(url.split('/').pop() || 'ExtensionSlice'));
                     if (!generatedAliasTypes.has(alias)) {
                         interfaces.unshift(`export interface ${alias} extends Extension { url: '${url}' }`);
                         generatedAliasTypes.add(alias);
@@ -1711,7 +1889,13 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
             for (const typeName of allFhirTypes) {
                 if (existingProfiles.has(typeName)) {
                     logger.log('[DEBUG local type]', { typeName });
-                    localTypes.push(typeName);
+                    // Never move FhirResource to local imports; it must stay from fhir/r4
+                    if (typeName !== 'FhirResource') {
+                        localTypes.push(typeName);
+                    }
+                    else {
+                        remainingFhirTypes.push(typeName);
+                    }
                 }
                 else {
                     logger.log('[DEBUG fhir type]', { typeName });

package/out/generator/sdParser.js

@@ -1,9 +1,23 @@
 import axios from "axios";
 import path from "path";
 import fs from "fs";
-import { logger } from "../logger";
 // Cache directory for fetched FHIR resources
 const CACHE_DIR = path.join(process.cwd(), ".cache", "fhir-resources");
+// Local StructureDefinitions indexed by canonical URL for fast lookup
+const localStructureDefinitions = new Map();
+/**
+ * Register local StructureDefinitions to enable resolution before HTTP fetch
+ */
+export function registerLocalStructureDefinitions(structureDefinitions) {
+    localStructureDefinitions.clear();
+    for (const sd of structureDefinitions) {
+        if (sd.url) {
+            localStructureDefinitions.set(sd.url, sd);
+            console.debug(`[sdParser] Registered local SD: ${sd.url}`);
+        }
+    }
+    console.log(`[sdParser] Registered ${localStructureDefinitions.size} local StructureDefinitions`);
+}
 function ensureCacheDir() {
     if (!fs.existsSync(CACHE_DIR)) {
         fs.mkdirSync(CACHE_DIR, { recursive: true });
@@ -19,6 +33,11 @@ function urlToFilename(url) {
  * Fetch a StructureDefinition from cache or network
  */
 export async function fetchStructureDefinition(url, fallbackUrl) {
+    // First, check if we have this SD registered locally (from input directory)
+    if (localStructureDefinitions.has(url)) {
+        console.debug(`[fetchSD] Found local StructureDefinition for ${url}`);
+        return localStructureDefinitions.get(url);
+    }
     const cacheFile = path.join(CACHE_DIR, urlToFilename(url));
     // Try to load from cache first
     if (fs.existsSync(cacheFile)) {
@@ -180,11 +199,11 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
             const baseField = baseFields.find(f => f.name === element.path);
             if (baseField) {
                 // Use base resource's array flag when profile doesn't override max
-                logger.log(`[sdParser] Using base cardinality for ${element.path}: baseField.isArray=${baseField.isArray}, element.max=${element.max}`);
+                console.log(`[sdParser] Using base cardinality for ${element.path}: baseField.isArray=${baseField.isArray}, element.max=${element.max}`);
                 isArray = baseField.isArray;
             }
             else {
-                logger.log(`[sdParser] No base field found for ${element.path}, using calculated isArray=${isArray}`);
+                console.log(`[sdParser] No base field found for ${element.path}, using calculated isArray=${isArray}`);
             }
         }
         const rawMax = element.max ?? '';
@@ -303,6 +322,15 @@ export async function parseStructureDefinition(structureDefinition, fhirServerUr
             max,
             typeOptions: typeOptions.length ? typeOptions : undefined,
         };
+        // Debug logging for mustSupport
+        if (process.env.DEBUG_FHIR_GEN === 'true' && (element.path?.includes('identifier') || element.path?.includes('status') || element.path?.includes('category'))) {
+            console.log(`[sdParser] Creating field for ${element.path}:`, {
+                elementMustSupport: element.mustSupport,
+                fieldMustSupport: field.mustSupport,
+                isOptional: field.isOptional,
+                min: element.min,
+            });
+        }
         return field;
     });
     return { newFields, oldFields: baseFields };
@@ -319,3 +347,34 @@ export async function fetchStructureDefinitions(fhirServerUrl) {
     }
     return resources;
 }
+/**
+ * Build a child field map for core FHIR types using official StructureDefinitions.
+ * Returns a Map where key is parent type name (e.g., 'Identifier') and value is a Map of
+ * child field name -> { type, isArray } based on the base (snapshot) definition.
+ */
+export async function buildFhirChildTypeMap(typeNames, fhirVersion = 'R4') {
+    const result = new Map();
+    for (const typeName of typeNames) {
+        try {
+            const sdUrl = `http://hl7.org/fhir/${fhirVersion}/StructureDefinition/${typeName}`;
+            const sd = await fetchStructureDefinition(sdUrl, '');
+            if (!sd)
+                continue;
+            const { newFields } = await parseStructureDefinition(sd, '');
+            const map = new Map();
+            for (const f of newFields) {
+                // Interested only in direct children of the type (e.g., Identifier.system)
+                const parts = f.name.split('.');
+                if (parts.length === 2 && parts[0] === typeName) {
+                    const child = parts[1];
+                    map.set(child, { type: f.type || 'any', isArray: f.isArray });
+                }
+            }
+            result.set(typeName, map);
+        }
+        catch {
+            // Best-effort; skip on failure
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babelfhir-ts",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4 StructureDefinitions (profiles) directly inside package archives.",
   "type": "module",
   "main": "out/main.js",