babelfhir-ts 1.3.10 → 1.4.0

package/README.md

@@ -202,7 +202,63 @@ const { errors, warnings } = await patient.validate();
 
 <!-- CLI_HELP_START -->
 ```
-
+BabelFHIR-TS: Generate TypeScript interfaces from FHIR StructureDefinitions
+
+Usage:
+  babelfhir-ts [options] [<input> [output]]
+  babelfhir-ts install [--package] <pkg[@version]|path> [--registry <url>] [options]
+  babelfhir-ts update [<pkg@version>] [--recursive] [options]
+
+Arguments:
+  input   Input can be:
+          - Canonical URL of a FHIR profile (http://... or https://...)
+          - Directory containing FHIR packages (.tgz/.zip files)
+          - Single FHIR package (.tgz/.zip file)
+          - Single StructureDefinition (.json file)
+          - Directory containing StructureDefinition files
+  output  Output directory or archive name (optional)
+
+Commands:
+  install                Download, process, and npm install package as dependency
+  update                 Regenerate all installed packages (or a specific one) with current babelfhir-ts
+
+Options:
+  -h, --help               Show this help message
+  -v, --version            Show version number
+  --log <dest>             Log destination: console (default) or file
+  --log-level <level>      Log verbosity: error, warn, info (default), or debug
+  --cache-dir <path>       Custom cache directory (default: ~/.fhir/packages for FHIR packages, .cache for working files)
+  --no-cache               Delete .cache working folder after generation (does not affect shared ~/.fhir/packages)
+  --no-classes             Only generate interfaces and types (skip class generation)
+  --no-client              Skip FHIR client generation (client generated by default)
+  --schema <format>        Generate schema files alongside outputs (supported: zod)
+  --dicomweb               Generate DICOMweb helpers typed to ImagingStudy profiles in the IG
+  --recursive              (update only) Recursively search subdirectories for lib/ folders
+  --outDir <dir>           Output directory (alias for second positional argument)
+  --fhir-version <ver>     FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)
+  --package <pkg[@version]>  Download FHIR package from registry and process it (latest if no version)
+  --registry <url>         FHIR package registry URL (default: https://packages.simplifier.net)
+  --tx-server <url>        Terminology server URL for ValueSet expansion (e.g., https://tx.fhir.org/r4)
+                           When set, expands ValueSets without explicit codes using $expand operation
+  --display-language <lang> BCP-47 language for display terms (e.g., de, fr). Passed to $expand displayLanguage
+
+Examples:
+  babelfhir-ts                                             # Process ./input to ./output
+  babelfhir-ts http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient  # Generate from profile URL
+  babelfhir-ts package.tgz                                 # Process package to current directory
+  babelfhir-ts package.tgz modified-package.tgz            # Embed interfaces in package
+  babelfhir-ts profiles/ generated/                        # Process directory to directory
+  babelfhir-ts --package hl7.fhir.us.core@8.0.0            # Download and process from default registry
+  babelfhir-ts --package hl7.fhir.us.core@8.0.0 output/    # Download and output to directory
+  babelfhir-ts --package pkg@version --log console --log-level debug  # With verbose logging
+  babelfhir-ts install de.gematik.isik-basismodul                           # Download latest, process, and install
+  babelfhir-ts install de.gematik.isik-basismodul@3.1.0                   # Download specific version
+  babelfhir-ts install ./package.tgz                                      # Install from local package file
+  babelfhir-ts install hl7.fhir.us.core@8.0.0 --registry <url>            # Install from custom registry
+  babelfhir-ts install --package hl7.fhir.us.core@8.0.0 --registry <url>  # Alternative syntax
+  babelfhir-ts update                                                      # Regenerate all packages in ./lib
+  babelfhir-ts update hl7.fhir.us.core@8.0.0                               # Regenerate a specific package
+  babelfhir-ts update --recursive                                          # Regenerate packages in all subdirectories
 ```
 <!-- CLI_HELP_END -->
 

package/out/src/cli/installCommand.js

@@ -63,6 +63,9 @@ export function buildInstallArgs(opts) {
             const deps = projectPkg.dependencies || {};
             for (const [, value] of Object.entries(deps)) {
                 if (typeof value === 'string' && (value === tgzRelPath || value === packagePath)) {
+                    // Dep already points to the tgz. Use a plain `install` (no add)
+                    // to avoid `bun add` creating duplicate keys in package.json.
+                    // The .bun cache nuke (clearBunCache) ensures bun re-extracts.
                     return { args: ['install'] };
                 }
             }
@@ -72,7 +75,7 @@ export function buildInstallArgs(opts) {
                     deps[name] = tgzRelPath;
                     projectPkg.dependencies = deps;
                     return {
-                        args: ['install'],
+                        args: [...pmArgs, tgzRelPath],
                         updatedPackageJson: JSON.stringify(projectPkg, null, 2) + '\n',
                     };
                 }
@@ -120,6 +123,49 @@ function npmInstall(packagePath) {
         });
     });
 }
+/**
+ * Bun caches extracted tgz content in `node_modules/.bun/<pkg>@<path-hash>/`.
+ * The cache key is derived from the file *path*, not its content, so replacing a
+ * tgz at the same path silently serves stale content — even with `--force`.
+ * This function removes those cache entries so the next `bun add` re-extracts.
+ * In monorepos the .bun cache lives at the workspace root, not in the app subdir,
+ * so we walk up the directory tree to find it (same as detectPackageManager).
+ * No-op when bun is not the package manager or no .bun cache dir is found.
+ */
+function clearBunCache(packageName) {
+    const pm = detectPackageManager();
+    if (!pm.cmd.includes('bun'))
+        return;
+    // Walk up to find node_modules/.bun — in monorepos it's at the workspace root.
+    let bunCacheDir = null;
+    let dir = process.cwd();
+    while (true) {
+        const candidate = path.join(dir, 'node_modules', '.bun');
+        if (fs.existsSync(candidate)) {
+            bunCacheDir = candidate;
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!bunCacheDir)
+        return;
+    // Entries look like: <pkg>@<encoded-path>+<hash>
+    // The package name may contain dots/scopes — match by startsWith.
+    const prefix = `${packageName}@`;
+    let removed = 0;
+    for (const entry of fs.readdirSync(bunCacheDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name.startsWith(prefix)) {
+            fs.rmSync(path.join(bunCacheDir, entry.name), { recursive: true, force: true });
+            removed++;
+        }
+    }
+    if (removed > 0) {
+        console.log(`Cleared ${removed} stale bun cache entr${removed === 1 ? 'y' : 'ies'} for ${packageName}`);
+    }
+}
 export async function handleInstallCommand(opts) {
     const { packageToInstall, registry, generationFlags, downloadPackage } = opts;
     // Keep cache by default — dependency packages are large (hl7.fhir.r4.core ~50 MB)
@@ -171,6 +217,11 @@ export async function handleInstallCommand(opts) {
             cwd: generatedDir,
             prefix: 'package'
         }, ['.']);
+        // Bun caches extracted tgz content keyed by file path, not content hash.
+        // When the tgz is regenerated at the same path, bun serves stale content.
+        // Workaround: nuke the .bun cache entry so bun is forced to re-extract.
+        // See: https://github.com/oven-sh/bun/issues/29372
+        clearBunCache(packageName);
         console.log(`Installing ${packageName}...`);
         await npmInstall(tarballPath);
         // Clean up extracted package tree (but keep the tarball under ./lib)

package/out/src/cli/updateCommand.js

@@ -0,0 +1,361 @@
+/**
+ * `babelfhir-ts update` command.
+ *
+ * Discovers generated tgz packages under ./lib (or recursively), regenerates
+ * them with the current babelfhir-ts version, repacks the tgz, and reinstalls.
+ *
+ * Usage:
+ *   babelfhir-ts update                          # update all in current project
+ *   babelfhir-ts update --recursive              # walk subdirectories too
+ *   babelfhir-ts update <package-name@version>   # update a single package
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { generateIntoPackageDirect, resetFetchFailureTracking } from '../generator/index.js';
+import { getFhirPackagesCacheDir } from '../generator/core/cacheConfig.js';
+import { resetDiagnostics, buildQualityReport, formatReportSummary } from '../generator/core/sdDiagnostics.js';
+import { detectPackageManager } from './installCommand.js';
+import { spawn } from 'child_process';
+// ── Public entry point ──────────────────────────────────────────────────────
+export async function handleUpdateCommand(opts) {
+    const { packageFilter, recursive, generationFlags, registry, downloadPackage, confirm } = opts;
+    const startDir = process.cwd();
+    // 1. Discover tgz files
+    const libDirs = discoverLibDirs(startDir, recursive ?? false);
+    if (libDirs.length === 0) {
+        if (packageFilter) {
+            return await promptInstallRedirect(packageFilter, confirm);
+        }
+        console.log('No lib/ directories found. Nothing to update.');
+        return {};
+    }
+    // 2. Read metadata from each tgz
+    const allTgz = await discoverTgzMetadata(libDirs);
+    if (allTgz.length === 0) {
+        if (packageFilter) {
+            return await promptInstallRedirect(packageFilter, confirm);
+        }
+        console.log('No generated packages found in lib/ directories.');
+        return {};
+    }
+    // 3. Filter if a specific package was requested
+    const targets = packageFilter ? filterBySpec(allTgz, packageFilter) : allTgz;
+    if (targets.length === 0 && packageFilter) {
+        console.log(`Package "${packageFilter}" is not installed.`);
+        if (allTgz.length > 0) {
+            console.log('Installed packages:');
+            for (const t of allTgz)
+                console.log(`  ${t.igName}@${t.igVersion}`);
+        }
+        return await promptInstallRedirect(packageFilter, confirm);
+    }
+    console.log(`Found ${targets.length} package${targets.length === 1 ? '' : 's'} to update:\n`);
+    for (const t of targets)
+        console.log(`  ${t.igName}@${t.igVersion}  →  ${path.relative(startDir, t.tgzPath)}`);
+    console.log('');
+    // 4. Regenerate each package
+    let updated = 0;
+    let failed = 0;
+    const updatedPackages = [];
+    for (const target of targets) {
+        try {
+            await regeneratePackage(target, generationFlags, registry, downloadPackage);
+            updatedPackages.push({ generatedName: target.generatedName, tgzPath: target.tgzPath });
+            updated++;
+        }
+        catch (err) {
+            failed++;
+            console.error(`✗ Failed to update ${target.igName}@${target.igVersion}: ${err.message}`);
+        }
+    }
+    // 5. Patch bun.lock integrity hashes for regenerated packages (avoids full lockfile delete)
+    if (updatedPackages.length > 0) {
+        patchBunLockIntegrity(updatedPackages);
+    }
+    // 6. Single npm install at the end
+    if (updated > 0) {
+        console.log('\nReinstalling dependencies...');
+        await runInstall();
+    }
+    // 7. Summary
+    console.log('');
+    if (updated > 0)
+        console.log(`✓ Updated ${updated} package${updated === 1 ? '' : 's'}`);
+    if (failed > 0)
+        console.error(`✗ ${failed} package${failed === 1 ? '' : 's'} failed`);
+    return {};
+}
+// ── Install redirect prompt ─────────────────────────────────────────────────
+async function promptInstallRedirect(packageFilter, confirm) {
+    const promptFn = confirm ?? defaultConfirm;
+    const yes = await promptFn(`Would you like to install ${packageFilter} instead? (Y/n) `);
+    if (yes)
+        return { redirectInstall: packageFilter };
+    return {};
+}
+/** Default Y/N prompt reading from stdin. */
+function defaultConfirm(question) {
+    return new Promise((resolve) => {
+        process.stdout.write(question);
+        const rl = (async () => {
+            const { createInterface } = await import('readline');
+            return createInterface({ input: process.stdin, output: process.stdout });
+        })();
+        rl.then(r => {
+            r.question('', (answer) => {
+                r.close();
+                resolve(!answer || answer.toLowerCase().startsWith('y'));
+            });
+        });
+    });
+}
+// ── Discovery ───────────────────────────────────────────────────────────────
+/** Find all lib/ directories starting from startDir. Non-recursive returns only startDir/lib. */
+function discoverLibDirs(startDir, recursive) {
+    const dirs = [];
+    const libDir = path.join(startDir, 'lib');
+    if (fs.existsSync(libDir) && fs.statSync(libDir).isDirectory()) {
+        dirs.push(libDir);
+    }
+    if (recursive) {
+        walkForLibDirs(startDir, dirs, 0);
+    }
+    return [...new Set(dirs)]; // deduplicate
+}
+/** Recursively walk looking for lib/ dirs (max depth 5, skip node_modules/.git) */
+function walkForLibDirs(dir, result, depth) {
+    if (depth > 5)
+        return;
+    const SKIP = new Set(['node_modules', '.git', '.cache', '.bun', 'dist', 'build']);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || SKIP.has(entry.name))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.name === 'lib') {
+            result.push(full);
+        }
+        else {
+            walkForLibDirs(full, result, depth + 1);
+        }
+    }
+}
+/** Read metadata from all .tgz files in the given lib directories. */
+async function discoverTgzMetadata(libDirs) {
+    const results = [];
+    const { list } = await import('tar');
+    for (const libDir of libDirs) {
+        const files = fs.readdirSync(libDir).filter(f => f.endsWith('.tgz'));
+        for (const file of files) {
+            const tgzPath = path.join(libDir, file);
+            const meta = await readTgzMetadata(tgzPath, list);
+            if (meta)
+                results.push(meta);
+        }
+    }
+    return results;
+}
+/** Extract package.json from a tgz and read fhir.ig + fhir.version metadata. */
+async function readTgzMetadata(tgzPath, listFn) {
+    let pkgJsonContent = '';
+    // Stream through the tgz looking for package/package.json
+    await listFn({
+        file: tgzPath,
+        onReadEntry: (entry) => {
+            const entryPath = entry.path.replace(/\\/g, '/');
+            if (entryPath === 'package/package.json' || entryPath === 'package.json') {
+                const chunks = [];
+                entry.on('data', (chunk) => chunks.push(chunk));
+                entry.on('end', () => { pkgJsonContent = Buffer.concat(chunks).toString('utf8'); });
+            }
+            else {
+                entry.resume(); // skip other entries
+            }
+        },
+    });
+    if (!pkgJsonContent)
+        return null;
+    try {
+        const pkg = JSON.parse(pkgJsonContent);
+        const igName = pkg?.fhir?.ig;
+        const igVersion = pkg?.fhir?.version;
+        if (!igName || !igVersion)
+            return null;
+        return {
+            tgzPath,
+            generatedName: pkg.name || '',
+            igName,
+            igVersion,
+            ...(pkg?.fhir?.txServer && { txServer: pkg.fhir.txServer }),
+            ...(pkg?.fhir?.displayLanguage && { displayLanguage: pkg.fhir.displayLanguage }),
+            ...(pkg?.fhir?.dicomweb && { dicomweb: true }),
+            ...(pkg?.fhir?.noClient && { noClient: true }),
+            ...(pkg?.fhir?.noClasses && { noClasses: true }),
+            ...(pkg?.fhir?.schema && { schema: pkg.fhir.schema }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Filtering ───────────────────────────────────────────────────────────────
+/** Filter metadata list by a package spec like "hl7.fhir.us.core" or "hl7.fhir.us.core@8.0.0" */
+function filterBySpec(all, spec) {
+    const atIdx = spec.lastIndexOf('@');
+    if (atIdx > 0) {
+        const name = spec.slice(0, atIdx);
+        const version = spec.slice(atIdx + 1);
+        return all.filter(t => t.igName === name && t.igVersion === version);
+    }
+    // No version — match by name only
+    return all.filter(t => t.igName === spec);
+}
+// ── Regeneration ────────────────────────────────────────────────────────────
+async function regeneratePackage(target, generationFlags, registry, downloadPackage) {
+    const spec = `${target.igName}@${target.igVersion}`;
+    console.log(`\nUpdating ${spec}...`);
+    // Locate the source package: check FHIR cache first, download if needed
+    const sourcePath = await resolveSourcePackage(target.igName, target.igVersion, registry, downloadPackage);
+    // Merge generation flags from package metadata (CLI flags take priority)
+    const mergedFlags = { ...generationFlags };
+    if (target.txServer && !mergedFlags.txServer) {
+        mergedFlags.txServer = target.txServer;
+        console.log(`  Using tx-server from package metadata: ${target.txServer}`);
+    }
+    if (target.displayLanguage && !mergedFlags.displayLanguage) {
+        mergedFlags.displayLanguage = target.displayLanguage;
+        console.log(`  Using display-language from package metadata: ${target.displayLanguage}`);
+    }
+    if (target.dicomweb && mergedFlags.dicomweb === undefined)
+        mergedFlags.dicomweb = true;
+    if (target.noClient && mergedFlags.noClient === undefined)
+        mergedFlags.noClient = true;
+    if (target.noClasses && mergedFlags.noClasses === undefined)
+        mergedFlags.noClasses = true;
+    if (target.schema && !mergedFlags.schema)
+        mergedFlags.schema = target.schema;
+    resetFetchFailureTracking();
+    resetDiagnostics();
+    // Generate
+    const { generatedDir, cleanup } = await generateIntoPackageDirect(sourcePath, mergedFlags);
+    try {
+        // Repack the tgz at the same path
+        const { create } = await import('tar');
+        await create({ gzip: true, file: target.tgzPath, cwd: generatedDir, prefix: 'package' }, ['.']);
+        // Clear bun cache for this package (same as install command)
+        clearBunCacheForPackage(target.generatedName);
+        console.log(`✓ Regenerated: ${path.basename(target.tgzPath)}`);
+        const report = buildQualityReport();
+        const summary = formatReportSummary(report);
+        if (summary.trim())
+            console.log(summary);
+    }
+    finally {
+        cleanup();
+    }
+}
+/** Find the source .tgz in the FHIR cache, or download it. */
+async function resolveSourcePackage(igName, igVersion, registry, downloadPackage) {
+    const cacheDir = getFhirPackagesCacheDir();
+    const tgzPath = path.join(cacheDir, `${igName}-${igVersion}.tgz`);
+    const extractedDir = path.join(cacheDir, `${igName}@${igVersion}`);
+    // If extracted dir exists (most common case after first install), return the tgz path
+    if (fs.existsSync(extractedDir) && fs.readdirSync(extractedDir).length > 0) {
+        // The tgz may or may not exist — generateIntoPackageDirect can work with either
+        if (fs.existsSync(tgzPath))
+            return tgzPath;
+        // If only extracted dir exists, we need to find or create a tgz
+        // Try to repack from extracted dir
+        const { create } = await import('tar');
+        await create({ gzip: true, file: tgzPath, cwd: extractedDir }, ['.']);
+        return tgzPath;
+    }
+    // Not cached — download
+    console.log(`  Package not in cache, downloading ${igName}@${igVersion}...`);
+    return downloadPackage(`${igName}@${igVersion}`, registry);
+}
+// ── Bun lockfile integrity patching ──────────────────────────────────────────
+/**
+ * Surgically update SHA-512 integrity hashes in bun.lock for regenerated tgz files.
+ *
+ * Bun stores integrity hashes in bun.lock (text format) as the third element
+ * of each package entry array: `["pkg@path", {deps}, "sha512-<base64>"]`.
+ * When a tgz is regenerated, the old hash becomes stale and `bun install`
+ * fails with "Integrity check failed". Instead of deleting the entire lockfile
+ * (which re-resolves ALL packages), we compute the new hash and patch only
+ * the affected entries.
+ *
+ * @see https://github.com/oven-sh/bun/issues/29372
+ */
+export function patchBunLockIntegrity(updatedPackages) {
+    const pm = detectPackageManager();
+    if (!pm.cmd.includes('bun'))
+        return;
+    const lockPath = path.resolve('bun.lock');
+    if (!fs.existsSync(lockPath))
+        return;
+    let lockContent = fs.readFileSync(lockPath, 'utf8');
+    let patched = 0;
+    for (const { generatedName, tgzPath } of updatedPackages) {
+        // Compute new SHA-512 integrity hash
+        const tgzBytes = fs.readFileSync(tgzPath);
+        const hash = crypto.createHash('sha512').update(tgzBytes).digest('base64');
+        const newIntegrity = `sha512-${hash}`;
+        // Match all entries for this package in bun.lock:
+        //   "hl7.fhir.uv.ips-generated": [..., "sha512-oldHash=="],
+        //   "workspace/hl7.fhir.uv.ips-generated": [..., "sha512-oldHash=="],
+        const pattern = new RegExp(`("(?:[^"]*\\/)?${escapeRegExp(generatedName)}"\\s*:\\s*\\[.*?)(sha512-[A-Za-z0-9+/]+=*)`, 'g');
+        lockContent = lockContent.replace(pattern, (_, prefix, _oldHash) => {
+            patched++;
+            return `${prefix}${newIntegrity}`;
+        });
+    }
+    if (patched > 0) {
+        fs.writeFileSync(lockPath, lockContent, 'utf8');
+        console.log(`Patched ${patched} integrity hash${patched === 1 ? '' : 'es'} in bun.lock`);
+    }
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ── Bun cache workaround ────────────────────────────────────────────────────
+function clearBunCacheForPackage(packageName) {
+    const pm = detectPackageManager();
+    if (!pm.cmd.includes('bun'))
+        return;
+    let dir = process.cwd();
+    while (true) {
+        const candidate = path.join(dir, 'node_modules', '.bun');
+        if (fs.existsSync(candidate)) {
+            const prefix = `${packageName}@`;
+            for (const entry of fs.readdirSync(candidate, { withFileTypes: true })) {
+                if (entry.isDirectory() && entry.name.startsWith(prefix)) {
+                    fs.rmSync(path.join(candidate, entry.name), { recursive: true, force: true });
+                }
+            }
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+}
+// ── Package manager install ─────────────────────────────────────────────────
+function runInstall() {
+    return new Promise((resolve, reject) => {
+        const pm = detectPackageManager();
+        const pmName = path.basename(pm.cmd).replace(/\.(cmd|exe)$/, '');
+        console.log(`Running ${pmName} install...`);
+        const child = spawn(pm.cmd, ['install'], { stdio: 'inherit', shell: true });
+        child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`${pmName} install failed (exit ${code})`)));
+        child.on('error', (err) => reject(new Error(`Failed to run ${pmName}: ${err.message}`)));
+    });
+}

package/out/src/generator/emitters/interface/interfaceFieldProcessor.js

@@ -414,11 +414,6 @@ export function processFields(ctx, fields, parentInterfaceName, parentFieldType,
                 treatAsNested = false;
             }
             else if (!isLogicalModelForNested) {
-                // Normally we flatten direct children of the base resource (e.g., DocumentReference.content)
-                // so we don't re-define backbone interfaces unnecessarily. However, if there are
-                // profiled descendants (e.g., DocumentReference.content.attachment with a profiled Attachment),
-                // we MUST keep this as a distinct nested interface so we can override those descendants while
-                // still extending the original backbone element type (e.g., DocumentReferenceContent).
                 const hasProfiledDescendant = fields.some(f => f.name.startsWith(field.name + '.') && f.isProfiled);
                 // Also keep as nested when the element has typed extension slices (e.g., Encounter.hospitalization.extension)
                 const hasChildExtSlices = fields.some(f => f.name === `${field.name}.extension` && f.sliceName && (f.profileUrls || []).length > 0);
@@ -428,8 +423,11 @@ export function processFields(ctx, fields, parentInterfaceName, parentFieldType,
                 else {
                     // Special case: primitive direct base child with child extension slices (e.g., gender)
                     // should NOT be modeled as a nested interface; the extension must live on sidecar _field Element.
+                    // Use field.type first — baseFieldByLastSegment can return wrong type due to
+                    // name collisions (e.g., 'text' resolves to Questionnaire.text=Narrative
+                    // instead of Questionnaire.item.text=string).
                     const baseFld = baseFieldByLastSegment.get(fieldName);
-                    const mappedBase = mapTypeToTS((baseFld?.type || field.type || 'string'));
+                    const mappedBase = mapTypeToTS((field.type || baseFld?.type || 'string'));
                     if (interfaceName.includes('address') && interfaceName.includes('0_2') && fieldName === 'line') {
                         logger.debug('[CHECK treatAsNested for line]', { hasChildExtSlices, isPrimitiveType: isPrimitiveType(mappedBase), mappedBase, baseFld: baseFld?.type, fieldType: field.type });
                     }

package/out/src/generator/emitters/interface/interfaceGenerator.js

@@ -7,7 +7,7 @@ import { getRules, ctx as versionCtx } from '../../fhir/versionContext.js';
 import { postProcessExtensions, safetyNetRootExtensions } from './postProcessExtensions.js';
 import { processFields } from './interfaceFieldProcessor.js';
 const log = logger.withTag('interfaces');
-export function generateInterfaces(interfaceName, newFields, baseResource, baseFields = [], valueSets, resourceType, existingProfiles, fhirChildTypeMap, profileIdToName, profileUrlToName) {
+export function generateInterfaces(interfaceName, newFields, baseResource, baseFields = [], valueSets, resourceType, existingProfiles, fhirChildTypeMap, profileIdToName, profileUrlToName, isLogicalModel = false) {
     const debug = (...args) => log.debug(...args);
     // Use FHIR rules from version context
     const rules = getRules();
@@ -151,6 +151,7 @@ export function generateInterfaces(interfaceName, newFields, baseResource, baseF
         resourceType, existingProfiles, fhirChildTypeMap, profileUrlToName,
         interfaces, localInterfaceNames, writtenLines, generatedAliasTypes,
         importManager, baseFieldByLastSegment, baseFieldAnyArray,
+        isLogicalModel,
         debug, addTypeImport, getBaseTypeForField, findInterfaceIndex,
         inferBackboneType, applyBindingConstraint,
     };

package/out/src/generator/emitters/interface/postProcessExtensions.js

@@ -289,35 +289,60 @@ export function postProcessExtensions(params) {
             }
             const union = ['Extension', ...aliases].join(' | ');
             const lvl2Name = `${lvl1Name}${capitalize(seg2)}`;
-            // Try to get base field type for seg2, then infer extend type
+            // Try to get base field type for seg2, then infer extend type.
+            // First check actual field type from newFields (path-aware) to avoid
+            // baseFieldByLastSegment collisions (e.g., 'text' → Questionnaire.text=Narrative
+            // instead of Questionnaire.item.text=string).
+            const actualField2 = newFields.find(f => {
+                const parts = f.name.split('.');
+                return parts.length >= 3 && parts[parts.length - 1] === seg2 && parts[parts.length - 2] === seg1;
+            });
             const baseFld2 = baseFieldByLastSegment.get(seg2);
-            let extendT2 = baseFld2?.type;
+            let extendT2 = actualField2?.type || baseFld2?.type;
             // Fallback to specific mappings if needed
             if (!extendT2 || extendT2 === 'any' || extendT2 === 'BackboneElement') {
                 if (baseResource === 'Encounter' && seg1 === 'hospitalization' && seg2 === 'dischargeDisposition') {
                     extendT2 = 'CodeableConcept';
                 }
             }
-            if (extendT2 && isFhirType(extendT2))
-                addTypeImport(extendT2);
-            const extendsClause2 = (extendT2 && !isPrimitiveType(extendT2)) ? ` extends ${extendT2}` : '';
-            if (!interfaces.some(i => i.startsWith(`export interface ${lvl2Name}`))) {
-                interfaces.push(`export interface ${lvl2Name}${extendsClause2} {\n    extension?: (${union})[];\n}`);
+            // If the actual field type is primitive, use Element sidecar pattern (_text, _prefix)
+            // instead of promoting to a complex interface. This avoids turning string fields
+            // into Narrative-extending interfaces when they have rendering extensions.
+            const extendT2TS = mapTypeToTS(extendT2 || 'string');
+            if (isPrimitiveLike(extendT2TS)) {
+                const elementIface = `${lvl1Name}${capitalize(seg2)}Element`;
+                importManager.addFhirType('Element');
+                if (!interfaces.some(i => i.startsWith(`export interface ${elementIface}`))) {
+                    interfaces.push(`export interface ${elementIface} extends Element {\n    extension?: (${union})[];\n}`);
+                }
+                else {
+                    appendToInterface(elementIface, `extension?: (${union})[];`);
+                }
+                const opt2 = actualField2 ? (actualField2.isOptional ? '?' : '') : (baseFld2 ? (baseFld2.isOptional ? '?' : '') : '?');
+                appendToInterface(lvl1Name, `_${seg2}${opt2}: ${elementIface};`);
             }
             else {
-                appendToInterface(lvl2Name, `extension?: (${union})[];`);
-            }
-            // Add property on level 1 interface - preserve arrayness from base
-            let isArr2 = baseFld2?.isArray;
-            if (isArr2 === undefined && extendT1) {
-                // Use FHIR type knowledge for the parent type (extendT1 is the type of lvl1)
-                isArr2 = isFhirFieldArray(extendT1, seg2);
-            }
-            const arrSuffix = isArr2 ? '[]' : '';
-            if (seg1 === 'code' || seg2 === 'coding') {
-                logger.debug('[DEBUG lvl2 property]', { seg1, seg2, baseFld2IsArray: baseFld2?.isArray, extendT1, isFhirCheck: isArr2, arrSuffix, lvl1Name, lvl2Name });
+                if (extendT2 && isFhirType(extendT2))
+                    addTypeImport(extendT2);
+                const extendsClause2 = (extendT2 && !isPrimitiveType(extendT2)) ? ` extends ${extendT2}` : '';
+                if (!interfaces.some(i => i.startsWith(`export interface ${lvl2Name}`))) {
+                    interfaces.push(`export interface ${lvl2Name}${extendsClause2} {\n    extension?: (${union})[];\n}`);
+                }
+                else {
+                    appendToInterface(lvl2Name, `extension?: (${union})[];`);
+                }
+                // Add property on level 1 interface - preserve arrayness from base
+                let isArr2 = baseFld2?.isArray;
+                if (isArr2 === undefined && extendT1) {
+                    // Use FHIR type knowledge for the parent type (extendT1 is the type of lvl1)
+                    isArr2 = isFhirFieldArray(extendT1, seg2);
+                }
+                const arrSuffix = isArr2 ? '[]' : '';
+                if (seg1 === 'code' || seg2 === 'coding') {
+                    logger.debug('[DEBUG lvl2 property]', { seg1, seg2, baseFld2IsArray: baseFld2?.isArray, extendT1, isFhirCheck: isArr2, arrSuffix, lvl1Name, lvl2Name });
+                }
+                appendToInterface(lvl1Name, `${seg2}: ${lvl2Name}${arrSuffix};`);
             }
-            appendToInterface(lvl1Name, `${seg2}: ${lvl2Name}${arrSuffix};`);
         }
     }
 }