@gefyra/diffyr6-cli 1.0.2 → 1.0.3

package/README.md

@@ -8,6 +8,7 @@ An automated toolkit for comparing FHIR profiles across different versions, anal
 - 🔄 **FSH Generation** - Converts FHIR resources to FSH using GoFSH  
 - ⬆️ **Profile Upgrade Pipeline** - Automatically upgrades profiles between FHIR versions using SUSHI
 - 📊 **Profile Comparison** - Compares profile versions using the HL7 FHIR Validator
+- 🎯 **Terminology Binding Analysis** - Compares terminology bindings between versions and checks ValueSet content from local package cache
 - 📝 **Rule-Based Difference Analysis** - Applies customizable rules to classify and score structural changes
 - 🎯 **Impact Scoring** - Calculates complexity scores based on breaking changes and migration risks
 - 🚨 **Removed Resource Detection** - Identifies profiles based on resource types removed in newer FHIR versions
@@ -166,7 +167,7 @@ console.log('Findings:', result.findingsCount);
 
 ## Pipeline Steps
 
-The comparison pipeline consists of 4 steps:
+The comparison pipeline consists of 5 steps:
 
 ### 1. GoFSH (Optional)
 
@@ -195,6 +196,19 @@ Applies rules to the comparison HTML files and generates a markdown report with:
 - Impact score based on breaking changes
 - Timestamped filename (e.g., `comparison-report-20260123-143052.md`)
 
+### 5. Terminology Binding Analysis
+
+Compares terminology bindings between R4 and R6 profiles:
+1. Runs `sushi -s` in both Resources and ResourcesR6 directories to generate snapshots
+2. Compares `element[].binding.strength` and `valueSet` between R4 and R6 profiles
+3. For ValueSets with version notation (pipe `|`), loads and compares content from local FHIR package cache:
+   - R4: `%USERPROFILE%\.fhir\packages\hl7.fhir.r4.core#4.0.1\package`
+   - R6: `%USERPROFILE%\.fhir\packages\hl7.fhir.r6.core#6.0.0-ballot3\package`
+4. Generates a `terminology-report-<timestamp>.md` with all binding differences
+5. Includes the report in the ZIP export
+
+**Note:** This step continues even if it fails, to ensure the main migration completes.
+
 ## Compare Modes
 
 ### Incremental Mode (Default)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gefyra/diffyr6-cli",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "FHIR R4 to R6 migration pipeline runner with automated profile comparison and rule-based analysis",
   "main": "src/index.js",
   "type": "module",

package/src/compare-terminology.js

@@ -0,0 +1,1004 @@
+import fsp from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { createAnimator, spawnProcess } from './utils/process.js';
+import { directoryExists, fileExists } from './utils/fs.js';
+
+/**
+ * Compares terminology bindings between R4 and R6 profiles
+ * 
+ * Steps:
+ * 1. Run sushi -s in Resources and ResourcesR6 directories to generate snapshots
+ * 2. Find all profile pairs from the comparison run
+ * 3. Compare element[].binding.strength and valueSet between R4 and R6
+ * 4. If valueSet has a version (pipe notation), compare the actual ValueSet content from local package cache
+ * 5. Generate a markdown report with all findings
+ * 
+ * @param {string} resourcesDir - R4 resources directory
+ * @param {string} resourcesR6Dir - R6 resources directory
+ * @param {string} outputDir - Output directory for the report
+ * @param {Object} options - Configuration options
+ * @returns {Promise<Object>} Report info with path and findings count
+ */
+export async function compareTerminology(resourcesDir, resourcesR6Dir, outputDir, options = {}) {
+  const { debug = false } = options;
+  
+  console.log('  Checking for existing snapshots...');
+  
+  // Step 1: Check if snapshots already exist, if not run sushi -s
+  const resourcesDirHasSnapshots = await hasSnapshots(resourcesDir);
+  const resourcesR6DirHasSnapshots = await hasSnapshots(resourcesR6Dir);
+  
+  if (resourcesDirHasSnapshots && resourcesR6DirHasSnapshots) {
+    console.log('  Snapshots already exist in both directories, skipping SUSHI build');
+  } else {
+    console.log('  Building snapshots with SUSHI...');
+    
+    try {
+      if (!resourcesDirHasSnapshots) {
+        await runSushiWithSnapshots(resourcesDir, debug);
+      } else {
+        console.log(`  Skipping ${path.basename(resourcesDir)} (snapshots already exist)`);
+      }
+      
+      if (!resourcesR6DirHasSnapshots) {
+        await runSushiWithSnapshots(resourcesR6Dir, debug);
+      } else {
+        console.log(`  Skipping ${path.basename(resourcesR6Dir)} (snapshots already exist)`);
+      }
+    } catch (error) {
+      throw new Error(`Failed to build snapshots: ${error.message}`);
+    }
+    
+    console.log('  Snapshots built successfully');
+  }
+  console.log('  Analyzing binding differences...');
+  
+  // Step 2-3: Collect profile pairs and compare bindings
+  const r4Profiles = await collectStructureDefinitions(resourcesDir);
+  const r6Profiles = await collectStructureDefinitions(resourcesR6Dir);
+  
+  const pairs = buildProfilePairs(r4Profiles, r6Profiles);
+  
+  if (pairs.length === 0) {
+    console.log('  No matching profile pairs found');
+    return null;
+  }
+  
+  const findings = [];
+  
+  for (const pair of pairs) {
+    const profileFindings = await compareProfileBindings(pair.r4, pair.r6, options);
+    if (profileFindings.length > 0) {
+      findings.push({
+        profileName: pair.name,
+        r4Url: pair.r4.url,
+        r6Url: pair.r6.url,
+        findings: profileFindings,
+      });
+    }
+  }
+  
+  console.log(`  Found ${findings.length} profile(s) with binding differences`);
+  
+  // Step 4: Identify common bindings across all profiles
+  const commonBindings = identifyCommonBindings(findings);
+  
+  // Remove common bindings from individual profiles
+  const filteredFindings = removeCommonBindingsFromProfiles(findings, commonBindings);
+  
+  // Step 5: Generate reports
+  const timestamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '').replace('T', '-');
+  const reportFilename = `terminology-report-${timestamp}.md`;
+  const reportPath = path.join(outputDir, reportFilename);
+  const jsonFilename = `terminology-report-${timestamp}.json`;
+  const jsonPath = path.join(outputDir, jsonFilename);
+  
+  // Generate markdown report
+  const markdown = generateTerminologyReport(filteredFindings, commonBindings);
+  await fsp.writeFile(reportPath, markdown, 'utf8');
+  
+  // Generate JSON report
+  const jsonData = {
+    generated: new Date().toISOString(),
+    profilesWithDifferences: filteredFindings.length,
+    totalFindings: filteredFindings.reduce((sum, p) => sum + p.findings.length, 0) + commonBindings.length,
+    commonBindings,
+    profiles: filteredFindings,
+  };
+  await fsp.writeFile(jsonPath, JSON.stringify(jsonData, null, 2), 'utf8');
+  
+  const totalFindings = filteredFindings.reduce((sum, p) => sum + p.findings.length, 0);
+  
+  return {
+    path: reportPath,
+    filename: reportFilename,
+    jsonPath,
+    jsonFilename,
+    profilesWithDifferences: filteredFindings.length,
+    totalFindings,
+  };
+}
+
+/**
+ * Check if snapshots already exist in the StructureDefinition files
+ */
+async function hasSnapshots(dir) {
+  const resourcesPath = path.join(dir, 'fsh-generated', 'resources');
+  const exists = await directoryExists(resourcesPath);
+  
+  if (!exists) {
+    return false;
+  }
+  
+  const files = await fsp.readdir(resourcesPath);
+  
+  // Check if at least one StructureDefinition has a snapshot
+  for (const file of files) {
+    if (!file.startsWith('StructureDefinition-') || !file.endsWith('.json')) {
+      continue;
+    }
+    
+    try {
+      const filePath = path.join(resourcesPath, file);
+      const content = await fsp.readFile(filePath, 'utf8');
+      const data = JSON.parse(content);
+      
+      if (data.resourceType === 'StructureDefinition' && data.snapshot && data.snapshot.element) {
+        // Found at least one StructureDefinition with snapshot
+        return true;
+      }
+    } catch (error) {
+      // Skip files that can't be read or parsed
+      continue;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Run sushi with snapshots flag in a directory
+ */
+async function runSushiWithSnapshots(dir, debug = false) {
+  const sushiConfigPath = path.join(dir, 'sushi-config.yaml');
+  const exists = await fileExists(sushiConfigPath);
+  
+  if (!exists) {
+    throw new Error(`sushi-config.yaml not found in ${dir}`);
+  }
+  
+  const dirName = path.basename(dir);
+  const animator = createAnimator(`SUSHI building snapshots for ${dirName}...`);
+  animator.start();
+  
+  try {
+    const result = await spawnProcess('sushi', ['-s'], dir, {
+      rejectOnNonZero: true,
+    });
+    
+    if (result.exitCode !== 0) {
+      if (debug) {
+        console.error('SUSHI stderr:', result.stderr);
+      }
+      throw new Error(`SUSHI failed in ${dir}: exit code ${result.exitCode}`);
+    }
+  } finally {
+    animator.stop();
+  }
+}
+
+/**
+ * Collect StructureDefinition files from a directory
+ */
+async function collectStructureDefinitions(rootDir) {
+  const resourcesPath = path.join(rootDir, 'fsh-generated', 'resources');
+  const exists = await directoryExists(resourcesPath);
+  
+  if (!exists) {
+    return [];
+  }
+  
+  const files = await fsp.readdir(resourcesPath);
+  const definitions = [];
+  
+  for (const file of files) {
+    if (!file.startsWith('StructureDefinition-') || !file.endsWith('.json')) {
+      continue;
+    }
+    
+    const filePath = path.join(resourcesPath, file);
+    const content = await fsp.readFile(filePath, 'utf8');
+    const data = JSON.parse(content);
+    
+    if (data.resourceType === 'StructureDefinition' && data.url) {
+      definitions.push({
+        url: data.url,
+        id: data.id || '',
+        name: data.name || '',
+        filePath,
+        data,
+      });
+    }
+  }
+  
+  return definitions;
+}
+
+/**
+ * Build profile pairs for comparison
+ */
+function buildProfilePairs(r4Profiles, r6Profiles) {
+  const pairs = [];
+  
+  // Create a map of R4 profiles by their last segment
+  const r4Map = new Map();
+  for (const r4 of r4Profiles) {
+    const segment = extractLastSegment(r4.url).toLowerCase();
+    r4Map.set(segment, r4);
+  }
+  
+  // Match R6 profiles to R4 profiles
+  for (const r6 of r6Profiles) {
+    const r6Segment = extractLastSegment(r6.url).toLowerCase();
+    
+    // Try direct match
+    let r4 = r4Map.get(r6Segment);
+    
+    // Try without version suffix
+    if (!r4) {
+      const withoutR6 = r6Segment.replace(/-?r6$/i, '');
+      r4 = r4Map.get(withoutR6) || r4Map.get(withoutR6 + '-r4') || r4Map.get(withoutR6 + 'r4');
+    }
+    
+    if (r4) {
+      pairs.push({
+        name: r6.name || r6.id || extractLastSegment(r6.url),
+        r4,
+        r6,
+      });
+    }
+  }
+  
+  return pairs;
+}
+
+/**
+ * Extract last segment from URL
+ */
+function extractLastSegment(url) {
+  if (!url) return '';
+  const hashIndex = url.lastIndexOf('#');
+  const slashIndex = url.lastIndexOf('/');
+  const index = Math.max(hashIndex, slashIndex);
+  return index >= 0 ? url.slice(index + 1) : url;
+}
+
+/**
+ * Compare bindings between two profiles
+ */
+async function compareProfileBindings(r4Profile, r6Profile, options = {}) {
+  const findings = [];
+  
+  // Get snapshots from both profiles
+  const r4Snapshot = r4Profile.data.snapshot?.element || [];
+  const r6Snapshot = r6Profile.data.snapshot?.element || [];
+  
+  // Create maps of elements by path
+  const r4Elements = new Map();
+  for (const elem of r4Snapshot) {
+    if (elem.binding) {
+      r4Elements.set(elem.path, elem);
+    }
+  }
+  
+  const r6Elements = new Map();
+  for (const elem of r6Snapshot) {
+    if (elem.binding) {
+      r6Elements.set(elem.path, elem);
+    }
+  }
+  
+  // Compare bindings for each element
+  for (const [path, r6Elem] of r6Elements) {
+    const r4Elem = r4Elements.get(path);
+    
+    if (!r4Elem) {
+      // New binding in R6
+      findings.push({
+        type: 'new-binding',
+        path,
+        r6Binding: r6Elem.binding,
+      });
+      continue;
+    }
+    
+    const r4Binding = r4Elem.binding;
+    const r6Binding = r6Elem.binding;
+    
+    // Check what changed
+    const strengthChanged = r4Binding.strength !== r6Binding.strength;
+    const valueSetChanged = r4Binding.valueSet !== r6Binding.valueSet;
+    
+    // If both changed, create a combined finding
+    if (strengthChanged && valueSetChanged) {
+      const finding = {
+        type: 'strength-and-valueset-change',
+        path,
+        r4Strength: r4Binding.strength,
+        r6Strength: r6Binding.strength,
+        r4ValueSet: r4Binding.valueSet,
+        r6ValueSet: r6Binding.valueSet,
+      };
+      
+      // If both have version, compare content
+      if (hasVersion(r4Binding.valueSet) && hasVersion(r6Binding.valueSet)) {
+        const contentDiff = await compareValueSetContent(
+          r4Binding.valueSet,
+          r6Binding.valueSet,
+          options
+        );
+        
+        if (contentDiff) {
+          finding.contentDifference = contentDiff;
+        }
+      }
+      
+      // Check if only version differs and no content changes
+      const onlyVersionChange = onlyVersionDiffers(r4Binding.valueSet, r6Binding.valueSet);
+      const hasContentChanges = finding.contentDifference && 
+                                 !finding.contentDifference.message &&
+                                 (finding.contentDifference.addedCount > 0 || 
+                                  finding.contentDifference.removedCount > 0);
+      
+      // If only version differs and no content changes, treat as strength-change only
+      if (onlyVersionChange && !hasContentChanges) {
+        findings.push({
+          type: 'strength-change',
+          path,
+          r4Strength: r4Binding.strength,
+          r6Strength: r6Binding.strength,
+          r4ValueSet: r4Binding.valueSet,
+          r6ValueSet: r6Binding.valueSet,
+        });
+      } else {
+        findings.push(finding);
+      }
+    } else if (strengthChanged) {
+      // Only strength changed
+      findings.push({
+        type: 'strength-change',
+        path,
+        r4Strength: r4Binding.strength,
+        r6Strength: r6Binding.strength,
+        r4ValueSet: r4Binding.valueSet,
+        r6ValueSet: r6Binding.valueSet,
+      });
+    } else if (valueSetChanged) {
+      // Only valueSet changed
+      const finding = {
+        type: 'valueset-change',
+        path,
+        r4ValueSet: r4Binding.valueSet,
+        r6ValueSet: r6Binding.valueSet,
+        r4Strength: r4Binding.strength,
+        r6Strength: r6Binding.strength,
+      };
+      
+      // If both have version, compare content
+      if (hasVersion(r4Binding.valueSet) && hasVersion(r6Binding.valueSet)) {
+        const contentDiff = await compareValueSetContent(
+          r4Binding.valueSet,
+          r6Binding.valueSet,
+          options
+        );
+        
+        if (contentDiff) {
+          finding.contentDifference = contentDiff;
+        }
+      }
+      
+      // Skip if only version differs and no content changes
+      const onlyVersionChange = onlyVersionDiffers(r4Binding.valueSet, r6Binding.valueSet);
+      const hasContentChanges = finding.contentDifference && 
+                                 !finding.contentDifference.message &&
+                                 (finding.contentDifference.addedCount > 0 || 
+                                  finding.contentDifference.removedCount > 0);
+      
+      // Only add finding if:
+      // - Version is different AND there are content changes, OR
+      // - The base URL is different (not just version)
+      if (!onlyVersionChange || hasContentChanges) {
+        findings.push(finding);
+      }
+    }
+  }
+  
+  // Check for removed bindings
+  for (const [path, r4Elem] of r4Elements) {
+    if (!r6Elements.has(path)) {
+      findings.push({
+        type: 'removed-binding',
+        path,
+        r4Binding: r4Elem.binding,
+      });
+    }
+  }
+  
+  return findings;
+}
+
+/**
+ * Check if valueSet URL has a version (pipe notation)
+ */
+function hasVersion(valueSetUrl) {
+  return valueSetUrl && valueSetUrl.includes('|');
+}
+
+/**
+ * Check if two ValueSet URLs differ only in version
+ */
+function onlyVersionDiffers(url1, url2) {
+  if (!url1 || !url2) return false;
+  
+  // Extract base URLs (without version)
+  const base1 = url1.split('|')[0];
+  const base2 = url2.split('|')[0];
+  
+  // If base URLs are the same, they only differ in version
+  return base1 === base2;
+}
+
+/**
+ * Compare ValueSet content from local package cache
+ */
+async function compareValueSetContent(r4ValueSetUrl, r6ValueSetUrl, options = {}) {
+  try {
+    const r4ValueSet = await loadValueSetFromCache(r4ValueSetUrl, '4.0.1');
+    const r6ValueSet = await loadValueSetFromCache(r6ValueSetUrl, '6.0.0-ballot3');
+    
+    if (!r4ValueSet || !r6ValueSet) {
+      return { message: 'Could not load ValueSets from cache' };
+    }
+    
+    // Extract all codes from both ValueSets
+    const r4Codes = await extractCodesFromValueSet(r4ValueSet, '4.0.1');
+    const r6Codes = await extractCodesFromValueSet(r6ValueSet, '6.0.0-ballot3');
+    
+    // Compare codes
+    const r4CodeSet = new Set(r4Codes.map(c => `${c.system}|${c.code}`));
+    const r6CodeSet = new Set(r6Codes.map(c => `${c.system}|${c.code}`));
+    
+    const addedCodes = [];
+    const removedCodes = [];
+    
+    // Find added codes
+    for (const codeKey of r6CodeSet) {
+      if (!r4CodeSet.has(codeKey)) {
+        const code = r6Codes.find(c => `${c.system}|${c.code}` === codeKey);
+        addedCodes.push(code);
+      }
+    }
+    
+    // Find removed codes
+    for (const codeKey of r4CodeSet) {
+      if (!r6CodeSet.has(codeKey)) {
+        const code = r4Codes.find(c => `${c.system}|${c.code}` === codeKey);
+        removedCodes.push(code);
+      }
+    }
+    
+    if (addedCodes.length === 0 && removedCodes.length === 0) {
+      return null; // No difference in codes
+    }
+    
+    return {
+      r4TotalCodes: r4Codes.length,
+      r6TotalCodes: r6Codes.length,
+      addedCodes: addedCodes.slice(0, 20), // Limit to first 20 for readability
+      removedCodes: removedCodes.slice(0, 20), // Limit to first 20 for readability
+      addedCount: addedCodes.length,
+      removedCount: removedCodes.length,
+    };
+  } catch (error) {
+    return { message: `Error comparing ValueSets: ${error.message}` };
+  }
+}
+
+/**
+ * Extract all codes from a ValueSet by processing compose.include
+ */
+async function extractCodesFromValueSet(valueSet, fhirVersion) {
+  const codes = [];
+  
+  if (!valueSet.compose || !valueSet.compose.include) {
+    return codes;
+  }
+  
+  for (const include of valueSet.compose.include) {
+    const system = include.system;
+    
+    if (!system) {
+      continue;
+    }
+    
+    // If specific concepts are listed, use those
+    if (include.concept && include.concept.length > 0) {
+      for (const concept of include.concept) {
+        codes.push({
+          system,
+          code: concept.code,
+          display: concept.display,
+        });
+      }
+    } else {
+      // Otherwise, try to load the entire CodeSystem
+      const codeSystem = await loadCodeSystemFromCache(system, fhirVersion);
+      if (codeSystem && codeSystem.concept) {
+        for (const concept of codeSystem.concept) {
+          addConceptAndChildren(codes, system, concept);
+        }
+      }
+    }
+  }
+  
+  // Handle excludes
+  if (valueSet.compose.exclude) {
+    const excludedCodes = new Set();
+    
+    for (const exclude of valueSet.compose.exclude) {
+      const system = exclude.system;
+      
+      if (exclude.concept) {
+        for (const concept of exclude.concept) {
+          excludedCodes.add(`${system}|${concept.code}`);
+        }
+      }
+    }
+    
+    // Filter out excluded codes
+    return codes.filter(c => !excludedCodes.has(`${c.system}|${c.code}`));
+  }
+  
+  return codes;
+}
+
+/**
+ * Recursively add concept and its children to the codes array
+ */
+function addConceptAndChildren(codes, system, concept) {
+  codes.push({
+    system,
+    code: concept.code,
+    display: concept.display,
+  });
+  
+  if (concept.concept && concept.concept.length > 0) {
+    for (const child of concept.concept) {
+      addConceptAndChildren(codes, system, child);
+    }
+  }
+}
+
+/**
+ * Load a CodeSystem from the local FHIR package cache
+ */
+async function loadCodeSystemFromCache(codeSystemUrl, fhirVersion) {
+  // Extract base URL without version
+  const [baseUrl] = codeSystemUrl.split('|');
+  
+  // Determine package path based on FHIR version
+  const userProfile = os.homedir();
+  let packagePath;
+  
+  if (fhirVersion.startsWith('4.')) {
+    packagePath = path.join(userProfile, '.fhir', 'packages', 'hl7.fhir.r4.core#4.0.1', 'package');
+  } else if (fhirVersion.startsWith('6.')) {
+    packagePath = path.join(userProfile, '.fhir', 'packages', 'hl7.fhir.r6.core#6.0.0-ballot3', 'package');
+  } else {
+    return null;
+  }
+  
+  // Check if package exists
+  const exists = await directoryExists(packagePath);
+  if (!exists) {
+    return null;
+  }
+  
+  // Search for CodeSystem file
+  const files = await fsp.readdir(packagePath);
+  
+  for (const file of files) {
+    if (!file.startsWith('CodeSystem-') || !file.endsWith('.json')) {
+      continue;
+    }
+    
+    try {
+      const filePath = path.join(packagePath, file);
+      const content = await fsp.readFile(filePath, 'utf8');
+      const data = JSON.parse(content);
+      
+      if (data.resourceType === 'CodeSystem' && data.url === baseUrl) {
+        return data;
+      }
+    } catch (error) {
+      // Skip files that can't be read or parsed
+      continue;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Load a ValueSet from the local FHIR package cache
+ */
+async function loadValueSetFromCache(valueSetUrl, fhirVersion) {
+  // Extract base URL without version
+  const [baseUrl, version] = valueSetUrl.split('|');
+  
+  // Determine package path based on FHIR version
+  const userProfile = os.homedir();
+  let packagePath;
+  
+  if (fhirVersion.startsWith('4.')) {
+    packagePath = path.join(userProfile, '.fhir', 'packages', 'hl7.fhir.r4.core#4.0.1', 'package');
+  } else if (fhirVersion.startsWith('6.')) {
+    packagePath = path.join(userProfile, '.fhir', 'packages', 'hl7.fhir.r6.core#6.0.0-ballot3', 'package');
+  } else {
+    return null;
+  }
+  
+  // Check if package exists
+  const exists = await directoryExists(packagePath);
+  if (!exists) {
+    return null;
+  }
+  
+  // Search for ValueSet file
+  const files = await fsp.readdir(packagePath);
+  
+  for (const file of files) {
+    if (!file.startsWith('ValueSet-') || !file.endsWith('.json')) {
+      continue;
+    }
+    
+    const filePath = path.join(packagePath, file);
+    const content = await fsp.readFile(filePath, 'utf8');
+    const data = JSON.parse(content);
+    
+    if (data.resourceType === 'ValueSet' && data.url === baseUrl) {
+      return data;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Identify bindings that are common across all profiles
+ */
+function identifyCommonBindings(findings) {
+  if (findings.length === 0) {
+    return [];
+  }
+  
+  // Build a map of finding signatures to count occurrences
+  const signatureMap = new Map();
+  
+  for (const profile of findings) {
+    const seenSignatures = new Set();
+    
+    for (const finding of profile.findings) {
+      // Create a signature for this finding (without the path's resource type prefix)
+      const pathWithoutResource = finding.path.replace(/^[^.]+\./, '');
+      const signature = createFindingSignature(finding, pathWithoutResource);
+      
+      if (!seenSignatures.has(signature)) {
+        seenSignatures.add(signature);
+        
+        if (!signatureMap.has(signature)) {
+          signatureMap.set(signature, {
+            count: 0,
+            finding: { ...finding, path: pathWithoutResource },
+          });
+        }
+        signatureMap.get(signature).count++;
+      }
+    }
+  }
+  
+  // Filter to findings that appear in all profiles
+  const commonFindings = [];
+  for (const [signature, data] of signatureMap) {
+    if (data.count === findings.length) {
+      commonFindings.push(data.finding);
+    }
+  }
+  
+  return commonFindings;
+}
+
+/**
+ * Create a signature for a finding to identify identical changes
+ */
+function createFindingSignature(finding, pathWithoutResource) {
+  const parts = [
+    finding.type,
+    pathWithoutResource,
+    finding.r4ValueSet || '',
+    finding.r6ValueSet || '',
+    finding.r4Strength || '',
+    finding.r6Strength || '',
+  ];
+  
+  return parts.join('||');
+}
+
+/**
+ * Remove common bindings from individual profile findings
+ */
+function removeCommonBindingsFromProfiles(findings, commonBindings) {
+  if (commonBindings.length === 0) {
+    return findings;
+  }
+  
+  // Create signatures for common bindings
+  const commonSignatures = new Set(
+    commonBindings.map(f => createFindingSignature(f, f.path))
+  );
+  
+  // Filter findings from each profile
+  const filtered = findings.map(profile => {
+    const filteredFindings = profile.findings.filter(finding => {
+      const pathWithoutResource = finding.path.replace(/^[^.]+\./, '');
+      const signature = createFindingSignature(finding, pathWithoutResource);
+      return !commonSignatures.has(signature);
+    });
+    
+    return {
+      ...profile,
+      findings: filteredFindings,
+    };
+  }).filter(profile => profile.findings.length > 0); // Remove profiles with no unique findings
+  
+  return filtered;
+}
+
+/**
+ * Group findings by type
+ */
+function groupFindingsByType(findings) {
+  const byType = {
+    'strength-and-valueset-change': [],
+    'strength-change': [],
+    'valueset-change': [],
+    'new-binding': [],
+    'removed-binding': [],
+  };
+  
+  for (const finding of findings) {
+    byType[finding.type].push(finding);
+  }
+  
+  return byType;
+}
+
+/**
+ * Append findings to markdown lines
+ */
+function appendFindingsToMarkdown(lines, byType) {
+  // Combined strength and valueset changes
+  if (byType['strength-and-valueset-change'].length > 0) {
+    lines.push('### Binding Strength and ValueSet Changes');
+    lines.push('');
+    
+    for (const f of byType['strength-and-valueset-change']) {
+      lines.push(`**${f.path}**`);
+      lines.push(`- Strength: \`${f.r4Strength}\` → \`${f.r6Strength}\``);
+      lines.push(`- R4 ValueSet: ${f.r4ValueSet || 'none'}`);
+      lines.push(`- R6 ValueSet: ${f.r6ValueSet || 'none'}`);
+      
+      if (f.contentDifference) {
+        lines.push('');
+        lines.push('**Content Difference:**');
+        
+        if (f.contentDifference.message) {
+          lines.push(`- ${f.contentDifference.message}`);
+        } else {
+          lines.push(`- R4 Total Codes: ${f.contentDifference.r4TotalCodes}`);
+          lines.push(`- R6 Total Codes: ${f.contentDifference.r6TotalCodes}`);
+          
+          if (f.contentDifference.addedCount > 0) {
+            lines.push(`- **Added Codes (${f.contentDifference.addedCount}):**`);
+            const addedCodes = f.contentDifference.addedCodes || [];
+            for (const code of addedCodes) {
+              const display = code.display ? ` - ${code.display}` : '';
+              lines.push(`  - \`${code.code}\`${display} (${code.system})`);
+            }
+            if (f.contentDifference.addedCount > addedCodes.length) {
+              lines.push(`  - ... and ${f.contentDifference.addedCount - addedCodes.length} more`);
+            }
+          }
+          
+          if (f.contentDifference.removedCount > 0) {
+            lines.push(`- **Removed Codes (${f.contentDifference.removedCount}):**`);
+            const removedCodes = f.contentDifference.removedCodes || [];
+            for (const code of removedCodes) {
+              const display = code.display ? ` - ${code.display}` : '';
+              lines.push(`  - \`${code.code}\`${display} (${code.system})`);
+            }
+            if (f.contentDifference.removedCount > removedCodes.length) {
+              lines.push(`  - ... and ${f.contentDifference.removedCount - removedCodes.length} more`);
+            }
+          }
+        }
+      }
+      
+      lines.push('');
+    }
+  }
+  
+  // Strength changes
+  if (byType['strength-change'].length > 0) {
+    lines.push('### Binding Strength Changes');
+    lines.push('');
+    
+    for (const f of byType['strength-change']) {
+      lines.push(`**${f.path}**`);
+      lines.push(`- Strength: \`${f.r4Strength}\` → \`${f.r6Strength}\``);
+      if (f.r4ValueSet) {
+        lines.push(`- ValueSet (R4): ${f.r4ValueSet}`);
+      }
+      if (f.r6ValueSet) {
+        lines.push(`- ValueSet (R6): ${f.r6ValueSet}`);
+      }
+      lines.push('');
+    }
+  }
+  
+  // ValueSet changes
+  if (byType['valueset-change'].length > 0) {
+    lines.push('### ValueSet Changes');
+    lines.push('');
+    
+    for (const f of byType['valueset-change']) {
+      lines.push(`**${f.path}**`);
+      lines.push(`- R4 ValueSet: ${f.r4ValueSet || 'none'}`);
+      lines.push(`- R6 ValueSet: ${f.r6ValueSet || 'none'}`);
+      
+      if (f.r4Strength || f.r6Strength) {
+        lines.push(`- Binding Strength: \`${f.r4Strength || 'none'}\` → \`${f.r6Strength || 'none'}\``);
+      }
+      
+      if (f.contentDifference) {
+        lines.push('');
+        lines.push('**Content Difference:**');
+        
+        if (f.contentDifference.message) {
+          lines.push(`- ${f.contentDifference.message}`);
+        } else {
+          lines.push(`- R4 Total Codes: ${f.contentDifference.r4TotalCodes}`);
+          lines.push(`- R6 Total Codes: ${f.contentDifference.r6TotalCodes}`);
+          
+          if (f.contentDifference.addedCount > 0) {
+            lines.push(`- **Added Codes (${f.contentDifference.addedCount}):**`);
+            const addedCodes = f.contentDifference.addedCodes || [];
+            for (const code of addedCodes) {
+              const display = code.display ? ` - ${code.display}` : '';
+              lines.push(`  - \`${code.code}\`${display} (${code.system})`);
+            }
+            if (f.contentDifference.addedCount > addedCodes.length) {
+              lines.push(`  - ... and ${f.contentDifference.addedCount - addedCodes.length} more`);
+            }
+          }
+          
+          if (f.contentDifference.removedCount > 0) {
+            lines.push(`- **Removed Codes (${f.contentDifference.removedCount}):**`);
+            const removedCodes = f.contentDifference.removedCodes || [];
+            for (const code of removedCodes) {
+              const display = code.display ? ` - ${code.display}` : '';
+              lines.push(`  - \`${code.code}\`${display} (${code.system})`);
+            }
+            if (f.contentDifference.removedCount > removedCodes.length) {
+              lines.push(`  - ... and ${f.contentDifference.removedCount - removedCodes.length} more`);
+            }
+          }
+        }
+      }
+      
+      lines.push('');
+    }
+  }
+  
+  // New bindings
+  if (byType['new-binding'].length > 0) {
+    lines.push('### New Bindings in R6');
+    lines.push('');
+    
+    for (const f of byType['new-binding']) {
+      lines.push(`**${f.path}**`);
+      if (f.r6Binding?.valueSet) {
+        lines.push(`- ValueSet: ${f.r6Binding.valueSet}`);
+      }
+      if (f.r6Binding?.strength) {
+        lines.push(`- Strength: \`${f.r6Binding.strength}\``);
+      }
+      lines.push('');
+    }
+  }
+  
+  // Removed bindings
+  if (byType['removed-binding'].length > 0) {
+    lines.push('### Removed Bindings in R6');
+    lines.push('');
+    
+    for (const f of byType['removed-binding']) {
+      lines.push(`**${f.path}**`);
+      if (f.r4Binding?.valueSet) {
+        lines.push(`- ValueSet (R4): ${f.r4Binding.valueSet}`);
+      }
+      if (f.r4Binding?.strength) {
+        lines.push(`- Strength (R4): \`${f.r4Binding.strength}\``);
+      }
+      lines.push('');
+    }
+  }
+}
+
+/**
+ * Generate markdown report for terminology comparison
+ */
+function generateTerminologyReport(findings, commonBindings = []) {
+  const lines = [];
+  
+  lines.push('# Terminology Binding Comparison Report');
+  lines.push('');
+  lines.push(`**Generated:** ${new Date().toISOString()}`);
+  lines.push(`**Profiles with Differences:** ${findings.length}`);
+  if (commonBindings.length > 0) {
+    lines.push(`**Common Bindings Across All Profiles:** ${commonBindings.length}`);
+  }
+  lines.push('');
+  lines.push('This report shows differences in terminology bindings between R4 and R6 profiles.');
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  
+  // Add common bindings section
+  if (commonBindings.length > 0) {
+    lines.push('## All Resources');
+    lines.push('');
+    lines.push('The following binding changes occur in **all** profiles:');
+    lines.push('');
+    
+    const groupedCommon = groupFindingsByType(commonBindings);
+    appendFindingsToMarkdown(lines, groupedCommon);
+    
+    lines.push('---');
+    lines.push('');
+  }
+  
+  if (findings.length === 0) {
+    lines.push('✅ **No profile-specific binding differences found.**');
+    lines.push('');
+    return lines.join('\n');
+  }
+  
+  for (const profile of findings) {
+    lines.push(`## ${profile.profileName}`);
+    lines.push('');
+    lines.push(`- **R4 URL:** ${profile.r4Url}`);
+    lines.push(`- **R6 URL:** ${profile.r6Url}`);
+    lines.push(`- **Differences:** ${profile.findings.length}`);
+    lines.push('');
+    
+    const groupedFindings = groupFindingsByType(profile.findings);
+    appendFindingsToMarkdown(lines, groupedFindings);
+    
+    lines.push('---');
+    lines.push('');
+  }
+  
+  return lines.join('\n');
+}

package/src/index.js

@@ -7,6 +7,7 @@ import { spawnProcess } from './utils/process.js';
 import { generateFshFromPackage } from './generate-fsh.js';
 import { upgradeSushiToR6 } from './upgrade-sushi.js';
 import { compareProfiles } from './compare-profiles.js';
+import { compareTerminology } from './compare-terminology.js';
 import { findRemovedResources } from './utils/removed-resources.js';
 import { createZip } from './utils/zip.js';
 
@@ -38,41 +39,53 @@ export async function runMigration(config) {
   if (config.enableGoFSH) {
     const shouldRunGoFSH = await checkShouldRunGoFSH(resourcesDir);
     if (shouldRunGoFSH) {
-      console.log('\n[1/4] Downloading package and generating FSH...');
+      console.log('\n[1/5] Downloading package and generating FSH...');
       await runGoFSH(context);
       context.steps.push('gofsh');
     } else {
-      console.log('\n[1/4] GoFSH - SKIPPED (Resources directory with sushi-config.yaml already exists)');
+      console.log('\n[1/5] GoFSH - SKIPPED (Resources directory with sushi-config.yaml already exists)');
     }
   } else {
-    console.log('\n[1/4] GoFSH - DISABLED in config');
+    console.log('\n[1/5] GoFSH - DISABLED in config');
   }
   
   // Step 2: Upgrade to R6
   const shouldRunUpgrade = await checkShouldRunUpgrade(resourcesR6Dir);
   if (shouldRunUpgrade) {
-    console.log('\n[2/4] Upgrading to R6...');
+    console.log('\n[2/5] Upgrading to R6...');
     await runUpgradeToR6(context);
     context.steps.push('upgrade');
   } else {
-    console.log('\n[2/4] Upgrade - SKIPPED (ResourcesR6 directory with sushi-config.yaml already exists)');
+    console.log('\n[2/5] Upgrade - SKIPPED (ResourcesR6 directory with sushi-config.yaml already exists)');
   }
   
   // Step 3: Compare profiles
-  console.log('\n[3/4] Comparing R4 vs R6 profiles...');
+  console.log('\n[3/5] Comparing R4 vs R6 profiles...');
   const compareResults = await runProfileComparison(context);
   context.steps.push('compare');
   
-  // Step 4: Generate report with rules
-  console.log('\n[4/4] Generating migration report...');
+  // Step 4: Generat5] Generating migration report...');
   const removedResources = await findRemovedResources(resourcesDir);
   const report = await generateReport(context, compareResults, removedResources);
   context.steps.push('report');
 
+  // Step 5: Compare terminology bindings
+  console.log('\n[5/5] Comparing terminology bindings...');
+  let terminologyReport = null;
+  try {
+    terminologyReport = await runTerminologyComparison(context);
+    if (terminologyReport) {
+      context.steps.push('terminology');
+    }
+  } catch (error) {
+    console.warn(`  Terminology comparison failed: ${error.message}`);
+    console.warn('  Continuing without terminology report...');
+  }
+
   let exportZipPath = null;
   if (config.exportZip) {
     console.log('\nGenerating export ZIP...');
-    exportZipPath = await exportComparisonZip(context, report);
+    exportZipPath = await exportComparisonZip(context, report, terminologyReport);
     context.steps.push('exportZip');
   }
   
@@ -153,6 +166,28 @@ async function runProfileComparison(context) {
   return [];
 }
 
+/**
+ * Run terminology comparison
+ */
+async function runTerminologyComparison(context) {
+  const { resourcesDir, resourcesR6Dir, outputDir, config } = context;
+  
+  const options = {
+    debug: config.debug || false,
+  };
+  
+  const result = await compareTerminology(resourcesDir, resourcesR6Dir, outputDir, options);
+  
+  if (result) {
+    console.log(`  ${result.profilesWithDifferences} profile(s) with binding differences`);
+    console.log(`  Total findings: ${result.totalFindings}`);
+    console.log(`  Markdown report: ${result.path}`);
+    console.log(`  JSON report: ${result.jsonPath}`);
+  }
+  
+  return result;
+}
+
 /**
  * Get list of profiles that need to be compared
  */
@@ -255,7 +290,7 @@ async function generateReport(context, compareResults, removedResources = []) {
 /**
  * Create a ZIP export with compare HTML files, report, and run config
  */
-async function exportComparisonZip(context, report) {
+async function exportComparisonZip(context, report, terminologyReport = null) {
   const { compareDir, outputDir, config } = context;
   const exportFilename = 'diffyr6-publish.zip';
   const exportPath = path.join(outputDir, exportFilename);
@@ -282,6 +317,26 @@ async function exportComparisonZip(context, report) {
     mtime: (await fsp.stat(report.path)).mtime,
   });
 
+  // Add terminology report if available
+  if (terminologyReport && terminologyReport.path) {
+    const termContent = await fsp.readFile(terminologyReport.path);
+    entries.push({
+      name: terminologyReport.filename,
+      data: termContent,
+      mtime: (await fsp.stat(terminologyReport.path)).mtime,
+    });
+    
+    // Add terminology JSON if available
+    if (terminologyReport.jsonPath) {
+      const termJsonContent = await fsp.readFile(terminologyReport.jsonPath);
+      entries.push({
+        name: terminologyReport.jsonFilename,
+        data: termJsonContent,
+        mtime: (await fsp.stat(terminologyReport.jsonPath)).mtime,
+      });
+    }
+  }
+
   // Add config used for the run
   entries.push({
     name: 'run-config.json',