@mitre/hdf-diff 3.0.1 → 3.1.0-rc.1

package/dist/diff.js

@@ -1,791 +0,0 @@
-import { computeEffectiveStatus, classifyChangeReasons, classifyDiffStatus } from './status.js';
-import { computeSummary } from './summary.js';
-import { normalizeToV2 } from './normalize.js';
-import { matchRequirements } from './matching/index.js';
-import { validateComparison } from './validate.js';
-import { diffSboms } from './sbom.js';
-const DEFAULT_TRACKED_FIELDS = ['impact', 'severity', 'tags'];
-/**
- * Extract a dataSource label from a document, if available.
- * Looks for `dataSource.name` in the raw (pre-normalized) document.
- */
-function extractDataSourceLabel(doc) {
-    const ds = doc['dataSource'];
-    if (ds && typeof ds['name'] === 'string') {
-        return ds['name'];
-    }
-    return undefined;
-}
-/**
- * Build MatchOptions from DiffOptions, extracting the matching-related fields.
- */
-function buildMatchOptions(options) {
-    return {
-        strategy: options?.matchStrategy,
-        fallbackStrategies: options?.fallbackStrategies,
-        mappingTable: options?.mappingTable,
-        minConfidence: options?.minConfidence,
-    };
-}
-/**
- * Determine the primary strategy name for the matching config output.
- */
-function resolveStrategyName(options) {
-    return options?.matchStrategy ?? 'exactId';
-}
-/**
- * Compare two HDF results documents and produce a structured comparison.
- *
- * Requirements are matched using a configurable matching strategy (default: exact ID).
- * Baselines are matched by `name`.
- *
- * For fleet mode, `newResults` can be an array of documents, each compared
- * pairwise against `oldResults` (the reference).
- */
-export function diffHdf(oldResults, newResults, options) {
-    const trackedFields = options?.trackedFields ?? DEFAULT_TRACKED_FIELDS;
-    let comparisonMode = options?.comparisonMode ?? 'temporal';
-    const matchOpts = buildMatchOptions(options);
-    // Auto-detect baseline evolution mode when both inputs are baseline documents
-    // (have requirements[] but no baselines[], targets[], or statistics[])
-    if (!options?.comparisonMode && !Array.isArray(newResults)) {
-        if (isBaselineDocument(oldResults) && isBaselineDocument(newResults)) {
-            comparisonMode = 'baselineEvolution';
-        }
-        else if (isSystemDocument(oldResults) && isSystemDocument(newResults)) {
-            comparisonMode = 'systemDrift';
-        }
-    }
-    // Validate array inputs up front (applies to all modes)
-    if (Array.isArray(newResults)) {
-        if (newResults.length === 0) {
-            throw new Error('newResults array must not be empty');
-        }
-        if (comparisonMode !== 'fleet' && newResults.length > 1) {
-            throw new Error(`Mode '${comparisonMode}' expects a single document, got ${newResults.length}. Use 'fleet' mode for multiple documents.`);
-        }
-    }
-    // Baseline evolution mode: compare two baseline documents
-    if (comparisonMode === 'baselineEvolution') {
-        const newDoc = Array.isArray(newResults) ? newResults[0] : newResults;
-        return diffBaselines(oldResults, newDoc, options);
-    }
-    // System drift mode: compare two system documents
-    if (comparisonMode === 'systemDrift') {
-        const newDoc = Array.isArray(newResults) ? newResults[0] : newResults;
-        return diffSystems(oldResults, newDoc, options);
-    }
-    // Fleet mode: compare reference against each system
-    if (comparisonMode === 'fleet') {
-        return diffFleet(oldResults, newResults, trackedFields, matchOpts);
-    }
-    // Non-fleet modes: newResults must be a single document
-    const newDoc = Array.isArray(newResults) ? newResults[0] : newResults;
-    // Normalize v1 (InSpec exec-json) to v2 if needed
-    const oldNormalized = normalizeToV2(oldResults);
-    const newNormalized = normalizeToV2(newDoc);
-    const oldTimestamp = oldNormalized['timestamp'];
-    const newTimestamp = newNormalized['timestamp'];
-    // Build sources metadata based on mode
-    const sources = buildSources(comparisonMode, oldResults, newDoc, oldTimestamp, newTimestamp);
-    // Compute baseline and requirement diffs
-    const { baselineDiffs, requirementDiffs } = comparePair(oldNormalized, newNormalized, oldTimestamp, newTimestamp, trackedFields, matchOpts);
-    // Sort by id
-    requirementDiffs.sort((a, b) => a.id.localeCompare(b.id));
-    // Extract drift: unchanged requirements with metadata changes
-    const drift = extractDrift(requirementDiffs);
-    const comparison = {
-        formatVersion: '1.0.0',
-        comparisonMode,
-        timestamp: new Date().toISOString(),
-        sources,
-        matching: {
-            primaryStrategy: resolveStrategyName(options),
-        },
-        summary: computeSummary(requirementDiffs),
-        baselineDiffs,
-        requirementDiffs,
-        drift,
-    };
-    if (options?.validateOutput) {
-        const result = validateComparison(comparison);
-        // Safety net: diffHdf always produces valid output by construction.
-        // This branch is unreachable in normal operation but guards against future regressions.
-        /* c8 ignore start */
-        if (!result.valid) {
-            throw new Error(`Output validation failed: ${result.errors?.join(', ')}`);
-        }
-        /* c8 ignore stop */
-    }
-    return comparison;
-}
-/**
- * Build source metadata entries based on comparison mode.
- */
-function buildSources(mode, oldDoc, newDoc, oldTimestamp, newTimestamp) {
-    switch (mode) {
-        case 'baseline':
-            return [
-                { role: 'golden', label: 'Golden baseline', assessmentTimestamp: oldTimestamp },
-                { role: 'new', label: 'Current scan', assessmentTimestamp: newTimestamp },
-            ];
-        case 'multiSource': {
-            const oldLabel = extractDataSourceLabel(oldDoc) ?? 'Old evaluation';
-            const newLabel = extractDataSourceLabel(newDoc) ?? 'New evaluation';
-            return [
-                { role: 'old', label: oldLabel, assessmentTimestamp: oldTimestamp },
-                { role: 'new', label: newLabel, assessmentTimestamp: newTimestamp },
-            ];
-        }
-        case 'temporal':
-        default:
-            return [
-                { role: 'old', label: 'Old evaluation', assessmentTimestamp: oldTimestamp },
-                { role: 'new', label: 'New evaluation', assessmentTimestamp: newTimestamp },
-            ];
-    }
-}
-/**
- * Fleet mode: compare a reference document against one or more system documents.
- * Each system is compared pairwise against the reference; all diffs are collected
- * into a single result with `sourceIndex` set on each RequirementDiff.
- */
-function diffFleet(referenceDoc, newResults, trackedFields, matchOpts) {
-    const systems = Array.isArray(newResults) ? newResults : [newResults];
-    const refNormalized = normalizeToV2(referenceDoc);
-    const refTimestamp = refNormalized['timestamp'];
-    // Build sources, compare each system against the reference, and collect diffs
-    // in a single pass — each system document is normalized exactly once.
-    const sources = [
-        { role: 'reference', label: 'Reference', assessmentTimestamp: refTimestamp },
-    ];
-    const allRequirementDiffs = [];
-    const allBaselineDiffs = [];
-    // Deduplicate baseline diffs by name: first-wins. In fleet mode, every system
-    // is compared against the same reference, so the first occurrence of a
-    // BaselineDiff for a given baseline name is representative. BaselineDiff does
-    // not carry a sourceIndex in v1 of the schema, so per-system baseline tracking
-    // is deferred to a future version.
-    const seenBaselineNames = new Set();
-    for (let i = 0; i < systems.length; i++) {
-        const sysNormalized = normalizeToV2(systems[i]);
-        const sysTimestamp = sysNormalized['timestamp'];
-        const sourceIndex = i + 1;
-        // Build the source entry for this system
-        sources.push({
-            role: 'system',
-            label: `System ${sourceIndex}`,
-            assessmentTimestamp: sysTimestamp,
-        });
-        const { baselineDiffs, requirementDiffs } = comparePair(refNormalized, sysNormalized, refTimestamp, sysTimestamp, trackedFields, matchOpts);
-        // Tag each requirement diff with its source index
-        for (const rd of requirementDiffs) {
-            rd.sourceIndex = sourceIndex;
-            allRequirementDiffs.push(rd);
-        }
-        // Collect baseline diffs (first-wins dedup; see comment above)
-        for (const bd of baselineDiffs) {
-            if (!seenBaselineNames.has(bd.name)) {
-                seenBaselineNames.add(bd.name);
-                allBaselineDiffs.push(bd);
-            }
-        }
-    }
-    // Sort by id, then by sourceIndex
-    allRequirementDiffs.sort((a, b) => {
-        const idCmp = a.id.localeCompare(b.id);
-        if (idCmp !== 0)
-            return idCmp;
-        /* c8 ignore next -- sourceIndex is always set in fleet mode; ?? 0 is defensive typing */
-        return (a.sourceIndex ?? 0) - (b.sourceIndex ?? 0);
-    });
-    // Extract drift: unchanged requirements with metadata changes
-    const drift = extractDrift(allRequirementDiffs);
-    return {
-        formatVersion: '1.0.0',
-        comparisonMode: 'fleet',
-        timestamp: new Date().toISOString(),
-        sources,
-        matching: {
-            primaryStrategy: matchOpts.strategy ?? 'exactId',
-        },
-        summary: computeSummary(allRequirementDiffs),
-        baselineDiffs: allBaselineDiffs,
-        requirementDiffs: allRequirementDiffs,
-        drift,
-    };
-}
-/**
- * Extract drift entries from requirement diffs.
- *
- * Drift = requirements whose effective status is unchanged but whose metadata
- * changed (tags, descriptions, impact score, etc.). These are the "silent"
- * changes that don't affect pass/fail outcome but still matter for auditing.
- *
- * Returns shallow copies so drift entries are independent of requirementDiffs.
- */
-function extractDrift(requirementDiffs) {
-    return requirementDiffs
-        .filter(r => r.state === 'unchanged' && r.changeReasons.length > 0)
-        .map(r => ({ ...r }));
-}
-/**
- * Core pairwise comparison between two normalized HDF documents.
- * Returns baseline diffs and requirement diffs without sorting or wrapping.
- *
- * Uses the pluggable matching system to pair requirements between evaluations.
- */
-function comparePair(oldNormalized, newNormalized, oldTimestamp, newTimestamp, trackedFields, matchOpts) {
-    const oldBaselines = oldNormalized['baselines'] ?? [];
-    const newBaselines = newNormalized['baselines'] ?? [];
-    // Build baseline maps by name
-    const oldBaselineMap = new Map();
-    for (const b of oldBaselines) {
-        oldBaselineMap.set(b.name, b);
-    }
-    const newBaselineMap = new Map();
-    for (const b of newBaselines) {
-        newBaselineMap.set(b.name, b);
-    }
-    // Compute baseline diffs
-    const allBaselineNames = new Set([...oldBaselineMap.keys(), ...newBaselineMap.keys()]);
-    const baselineDiffs = [];
-    for (const name of allBaselineNames) {
-        const oldB = oldBaselineMap.get(name);
-        const newB = newBaselineMap.get(name);
-        if (oldB && newB) {
-            const versionChanged = oldB.version !== newB.version;
-            baselineDiffs.push({
-                name,
-                oldVersion: oldB.version,
-                newVersion: newB.version,
-                state: versionChanged ? 'updated' : 'unchanged',
-            });
-        }
-        else if (oldB && !newB) {
-            baselineDiffs.push({
-                name,
-                oldVersion: oldB.version,
-                state: 'absent',
-            });
-        }
-        else if (!oldB && newB) {
-            baselineDiffs.push({
-                name,
-                newVersion: newB.version,
-                state: 'new',
-            });
-        }
-    }
-    // Collect all requirements across all baselines
-    const oldReqs = [];
-    for (const baseline of oldBaselines) {
-        for (const req of baseline.requirements) {
-            oldReqs.push(req);
-        }
-    }
-    const newReqs = [];
-    for (const baseline of newBaselines) {
-        for (const req of baseline.requirements) {
-            newReqs.push(req);
-        }
-    }
-    // Use the matching system to pair requirements
-    const matchResult = matchRequirements(oldReqs, newReqs, matchOpts);
-    // Build requirement diffs from match results
-    const requirementDiffs = [];
-    // Matched pairs
-    for (const pair of matchResult.matched) {
-        const oldReq = pair.oldReq;
-        const newReq = pair.newReq;
-        /* c8 ignore next -- id is always a string on RequirementLike; ?? is defensive typing */
-        const id = (newReq.id ?? oldReq.id);
-        const oldStatus = computeEffectiveStatus(oldReq, oldTimestamp);
-        const newStatus = computeEffectiveStatus(newReq, newTimestamp);
-        const diffState = classifyDiffStatus(oldStatus, newStatus);
-        const changeReasons = classifyChangeReasons(oldReq, newReq, oldTimestamp, newTimestamp);
-        const fieldChanges = computeFieldChanges(oldReq, newReq, trackedFields);
-        requirementDiffs.push({
-            id,
-            title: newReq.title ?? oldReq.title,
-            state: diffState,
-            oldEffectiveStatus: oldStatus,
-            newEffectiveStatus: newStatus,
-            changeReasons,
-            oldImpact: oldReq.impact,
-            newImpact: newReq.impact,
-            fieldChanges,
-            before: oldReq,
-            after: newReq,
-            matchStrategy: pair.strategy,
-            matchConfidence: pair.confidence,
-        });
-    }
-    // Unmatched old requirements (absent)
-    for (const req of matchResult.unmatchedOld) {
-        const oldReq = req;
-        const id = oldReq.id;
-        const oldStatus = computeEffectiveStatus(oldReq, oldTimestamp);
-        requirementDiffs.push({
-            id,
-            title: oldReq.title,
-            state: 'absent',
-            oldEffectiveStatus: oldStatus,
-            changeReasons: [],
-            oldImpact: oldReq.impact,
-            fieldChanges: [],
-            before: oldReq,
-            after: null,
-        });
-    }
-    // Unmatched new requirements (new)
-    for (const req of matchResult.unmatchedNew) {
-        const newReq = req;
-        const id = newReq.id;
-        const newStatus = computeEffectiveStatus(newReq, newTimestamp);
-        requirementDiffs.push({
-            id,
-            title: newReq.title,
-            state: 'new',
-            newEffectiveStatus: newStatus,
-            changeReasons: [],
-            newImpact: newReq.impact,
-            fieldChanges: [],
-            before: null,
-            after: newReq,
-        });
-    }
-    return { baselineDiffs, requirementDiffs };
-}
-/**
- * Compute field-level changes for tracked fields between two requirements.
- * Uses JSON Patch-like op/path format.
- */
-function computeFieldChanges(oldReq, newReq, trackedFields) {
-    const changes = [];
-    for (const field of trackedFields) {
-        const oldVal = oldReq[field];
-        const newVal = newReq[field];
-        // Deep comparison for objects/arrays
-        if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
-            if (oldVal === undefined && newVal !== undefined) {
-                changes.push({
-                    op: 'add',
-                    path: field,
-                    newValue: newVal,
-                });
-            }
-            else if (oldVal !== undefined && newVal === undefined) {
-                changes.push({
-                    op: 'remove',
-                    path: field,
-                    oldValue: oldVal,
-                });
-            }
-            else {
-                changes.push({
-                    op: 'replace',
-                    path: field,
-                    oldValue: oldVal,
-                    newValue: newVal,
-                });
-            }
-        }
-    }
-    return changes;
-}
-/**
- * Detect whether a document is a baseline (not results).
- * Baselines have `requirements` at the top level and lack `baselines`, `targets`, and `statistics`.
- */
-function isBaselineDocument(doc) {
-    return (Array.isArray(doc['requirements']) &&
-        !Array.isArray(doc['baselines']) &&
-        !Array.isArray(doc['targets']) &&
-        doc['statistics'] === undefined);
-}
-/** Default tracked fields for baseline evolution comparisons. */
-const BASELINE_TRACKED_FIELDS = ['title', 'impact', 'descriptions', 'tags'];
-/**
- * Compare two HDF baseline documents and produce a structured comparison
- * showing requirement changes between baseline versions.
- *
- * Unlike diffHdf (which compares results/evaluations), this compares baseline
- * definitions — requirements without results. There is no status-based classification
- * (fixed/regressed); only metadata changes (title, impact, descriptions, tags) are tracked.
- */
-export function diffBaselines(oldBaseline, newBaseline, options) {
-    const trackedFields = options?.trackedFields ?? BASELINE_TRACKED_FIELDS;
-    const matchOpts = buildMatchOptions(options);
-    // Extract requirements from baseline documents
-    const oldReqs = oldBaseline['requirements'] ?? [];
-    const newReqs = newBaseline['requirements'] ?? [];
-    // Use the matching system to pair requirements
-    const matchResult = matchRequirements(oldReqs, newReqs, matchOpts);
-    // Build requirement diffs from match results
-    const requirementDiffs = [];
-    // Matched pairs
-    for (const pair of matchResult.matched) {
-        const oldReq = pair.oldReq;
-        const newReq = pair.newReq;
-        const id = (newReq.id ?? oldReq.id);
-        const fieldChanges = computeFieldChanges(oldReq, newReq, trackedFields);
-        // For baseline evolution, state is determined by metadata changes only
-        const state = fieldChanges.length > 0 ? 'updated' : 'unchanged';
-        // Determine change reasons for baseline evolution
-        const changeReasons = [];
-        if (oldReq.impact !== newReq.impact) {
-            changeReasons.push('impactChanged');
-        }
-        const oldTags = JSON.stringify(oldReq['tags'] ?? {});
-        const newTags = JSON.stringify(newReq['tags'] ?? {});
-        const oldDescs = JSON.stringify(oldReq['descriptions'] ?? []);
-        const newDescs = JSON.stringify(newReq['descriptions'] ?? []);
-        const oldTitle = oldReq['title'];
-        const newTitle = newReq['title'];
-        if (oldTags !== newTags || oldDescs !== newDescs || oldTitle !== newTitle) {
-            changeReasons.push('metadataChanged');
-        }
-        requirementDiffs.push({
-            id,
-            title: newReq.title ?? oldReq.title,
-            state,
-            changeReasons,
-            oldImpact: oldReq.impact,
-            newImpact: newReq.impact,
-            fieldChanges,
-            before: oldReq,
-            after: newReq,
-            matchStrategy: pair.strategy,
-            matchConfidence: pair.confidence,
-        });
-    }
-    // Unmatched old requirements (absent)
-    for (const req of matchResult.unmatchedOld) {
-        const oldReq = req;
-        requirementDiffs.push({
-            id: oldReq.id,
-            title: oldReq.title,
-            state: 'absent',
-            changeReasons: [],
-            oldImpact: oldReq.impact,
-            fieldChanges: [],
-            before: oldReq,
-            after: null,
-        });
-    }
-    // Unmatched new requirements (new)
-    for (const req of matchResult.unmatchedNew) {
-        const newReq = req;
-        requirementDiffs.push({
-            id: newReq.id,
-            title: newReq.title,
-            state: 'new',
-            changeReasons: [],
-            newImpact: newReq.impact,
-            fieldChanges: [],
-            before: null,
-            after: newReq,
-        });
-    }
-    // Sort by id
-    requirementDiffs.sort((a, b) => a.id.localeCompare(b.id));
-    // Build baseline diff from top-level baseline metadata
-    const oldName = oldBaseline['name'] ?? '';
-    const newName = newBaseline['name'] ?? '';
-    const oldVersion = oldBaseline['version'];
-    const newVersion = newBaseline['version'];
-    const baselineDiffs = [];
-    const baselineName = newName || oldName;
-    if (baselineName) {
-        const versionChanged = oldVersion !== newVersion;
-        baselineDiffs.push({
-            name: baselineName,
-            oldVersion,
-            newVersion,
-            state: versionChanged ? 'updated' : 'unchanged',
-        });
-    }
-    // Build sources
-    const sources = [
-        { role: 'old', label: oldVersion ? `${baselineName} ${oldVersion}` : baselineName || 'Old baseline' },
-        { role: 'new', label: newVersion ? `${baselineName} ${newVersion}` : baselineName || 'New baseline' },
-    ];
-    const comparison = {
-        formatVersion: '1.0.0',
-        comparisonMode: 'baselineEvolution',
-        timestamp: new Date().toISOString(),
-        sources,
-        matching: {
-            primaryStrategy: resolveStrategyName(options),
-        },
-        summary: computeSummary(requirementDiffs),
-        baselineDiffs,
-        requirementDiffs,
-    };
-    if (options?.validateOutput) {
-        const result = validateComparison(comparison);
-        /* c8 ignore start */
-        if (!result.valid) {
-            throw new Error(`Output validation failed: ${result.errors?.join(', ')}`);
-        }
-        /* c8 ignore stop */
-    }
-    return comparison;
-}
-/**
- * Detect whether a document is a system document (has components[] but no baselines/requirements).
- */
-function isSystemDocument(doc) {
-    return (Array.isArray(doc['components']) &&
-        !Array.isArray(doc['baselines']) &&
-        !Array.isArray(doc['requirements']) &&
-        doc['statistics'] === undefined);
-}
-/** Fields tracked for system-level field changes. */
-const SYSTEM_TOP_LEVEL_FIELDS = ['authorizationStatus', 'categorizationLevel', 'description'];
-/** Fields tracked for component-level field changes. */
-const COMPONENT_TRACKED_FIELDS = [
-    'type', 'description', 'baselineRefs', 'inputOverrides', 'sbomRef', 'targetSelector',
-];
-/**
- * Compare two HDF system documents and produce a structured comparison
- * showing component-level changes between system versions.
- *
- * Components are matched by componentId (UUID) when available, falling back
- * to exact name matching. Top-level system fields, data flows, and embedded
- * SBOMs are also compared.
- */
-export function diffSystems(oldSystem, newSystem, options) {
-    const oldComponents = oldSystem['components'] ?? [];
-    const newComponents = newSystem['components'] ?? [];
-    // Match components: prefer componentId, fall back to name
-    const pairs = matchComponents(oldComponents, newComponents);
-    const componentDiffs = [];
-    for (const { oldComp, newComp, name } of pairs) {
-        if (oldComp && newComp) {
-            const fieldChanges = computeComponentFieldChanges(oldComp, newComp, COMPONENT_TRACKED_FIELDS);
-            const state = fieldChanges.length > 0 ? 'updated' : 'unchanged';
-            componentDiffs.push({ name, state, before: oldComp, after: newComp, fieldChanges });
-        }
-        else if (oldComp && !newComp) {
-            componentDiffs.push({ name, state: 'absent', before: oldComp, after: null, fieldChanges: [] });
-        }
-        else if (!oldComp && newComp) {
-            componentDiffs.push({ name, state: 'new', before: null, after: newComp, fieldChanges: [] });
-        }
-    }
-    componentDiffs.sort((a, b) => a.name.localeCompare(b.name));
-    // Compare top-level system fields
-    const systemFieldChanges = computeComponentFieldChanges(oldSystem, newSystem, SYSTEM_TOP_LEVEL_FIELDS);
-    // Build summary counts based on component diffs
-    const counts = { new: 0, absent: 0, unchanged: 0, updated: 0 };
-    for (const cd of componentDiffs) {
-        counts[cd.state]++;
-    }
-    const oldName = oldSystem['name'] ?? '';
-    const newName = newSystem['name'] ?? '';
-    const systemName = newName || oldName;
-    const sources = [
-        { role: 'old', label: systemName ? `${systemName} (old)` : 'Old system' },
-        { role: 'new', label: systemName ? `${systemName} (new)` : 'New system' },
-    ];
-    const comparison = {
-        formatVersion: '1.0.0',
-        comparisonMode: 'systemDrift',
-        timestamp: new Date().toISOString(),
-        sources,
-        summary: {
-            total: pairs.length,
-            matchedCount: counts.unchanged + counts.updated,
-            unmatchedOldCount: counts.absent,
-            unmatchedNewCount: counts.new,
-            new: counts.new,
-            absent: counts.absent,
-            unchanged: counts.unchanged,
-            updated: counts.updated,
-            fixed: 0,
-            regressed: 0,
-        },
-        baselineDiffs: [],
-        requirementDiffs: [],
-        componentDiffs,
-    };
-    // Extensions: system field changes + data flow changes
-    const extensions = {};
-    if (systemFieldChanges.length > 0) {
-        extensions['systemFieldChanges'] = systemFieldChanges;
-    }
-    const dataFlowChanges = diffDataFlows(oldSystem, newSystem);
-    if (dataFlowChanges.length > 0) {
-        extensions['dataFlowChanges'] = dataFlowChanges;
-    }
-    if (Object.keys(extensions).length > 0) {
-        comparison.extensions = extensions;
-    }
-    // Diff embedded SBOMs across matched components
-    const allPackageDiffs = diffEmbeddedSboms(pairs);
-    if (allPackageDiffs.length > 0) {
-        comparison.packageDiffs = allPackageDiffs;
-    }
-    if (options?.validateOutput) {
-        const result = validateComparison(comparison);
-        /* c8 ignore start */
-        if (!result.valid) {
-            throw new Error(`Output validation failed: ${result.errors?.join(', ')}`);
-        }
-        /* c8 ignore stop */
-    }
-    return comparison;
-}
-/**
- * Match old and new components by componentId (when available) or name.
- */
-function matchComponents(oldComponents, newComponents) {
-    const matched = new Set(); // indices of matched new components
-    const pairs = [];
-    // First pass: match by componentId
-    const newById = new Map();
-    for (let i = 0; i < newComponents.length; i++) {
-        const id = newComponents[i]['componentId'];
-        if (id)
-            newById.set(id, i);
-    }
-    const oldMatched = new Set();
-    for (let i = 0; i < oldComponents.length; i++) {
-        const oldId = oldComponents[i]['componentId'];
-        if (oldId && newById.has(oldId)) {
-            const ni = newById.get(oldId);
-            const newComp = newComponents[ni];
-            pairs.push({
-                name: newComp['name'] || oldComponents[i]['name'] || oldId,
-                oldComp: oldComponents[i],
-                newComp,
-            });
-            matched.add(ni);
-            oldMatched.add(i);
-        }
-    }
-    // Second pass: match remaining by name
-    const newByName = new Map();
-    for (let i = 0; i < newComponents.length; i++) {
-        if (matched.has(i))
-            continue;
-        const name = newComponents[i]['name'];
-        if (name)
-            newByName.set(name, i);
-    }
-    for (let i = 0; i < oldComponents.length; i++) {
-        if (oldMatched.has(i))
-            continue;
-        const name = oldComponents[i]['name'];
-        if (name && newByName.has(name)) {
-            const ni = newByName.get(name);
-            pairs.push({ name, oldComp: oldComponents[i], newComp: newComponents[ni] });
-            matched.add(ni);
-            oldMatched.add(i);
-            newByName.delete(name);
-        }
-    }
-    // Unmatched old → absent
-    for (let i = 0; i < oldComponents.length; i++) {
-        if (oldMatched.has(i))
-            continue;
-        const name = oldComponents[i]['name'] || `component-${i}`;
-        pairs.push({ name, oldComp: oldComponents[i], newComp: undefined });
-    }
-    // Unmatched new → new
-    for (let i = 0; i < newComponents.length; i++) {
-        if (matched.has(i))
-            continue;
-        const name = newComponents[i]['name'] || `component-${i}`;
-        pairs.push({ name, oldComp: undefined, newComp: newComponents[i] });
-    }
-    return pairs;
-}
-/**
- * Diff data flows between two system documents. Flows are keyed by from+to.
- */
-function diffDataFlows(oldSystem, newSystem) {
-    const oldFlows = oldSystem['dataFlows'] ?? [];
-    const newFlows = newSystem['dataFlows'] ?? [];
-    if (oldFlows.length === 0 && newFlows.length === 0)
-        return [];
-    const flowKey = (f) => {
-        const from = f['from'] ?? '';
-        const to = typeof f['to'] === 'string' ? f['to'] : JSON.stringify(f['to']);
-        return `${from}→${to}`;
-    };
-    const oldMap = new Map();
-    for (const f of oldFlows)
-        oldMap.set(flowKey(f), f);
-    const newMap = new Map();
-    for (const f of newFlows)
-        newMap.set(flowKey(f), f);
-    const allKeys = new Set([...oldMap.keys(), ...newMap.keys()]);
-    const changes = [];
-    for (const key of allKeys) {
-        const oldF = oldMap.get(key);
-        const newF = newMap.get(key);
-        if (oldF && newF) {
-            if (JSON.stringify(oldF) !== JSON.stringify(newF)) {
-                changes.push({ state: 'updated', flow: newF });
-            }
-        }
-        else if (oldF && !newF) {
-            changes.push({ state: 'removed', flow: oldF });
-        }
-        else if (!oldF && newF) {
-            changes.push({ state: 'added', flow: newF });
-        }
-    }
-    return changes;
-}
-/**
- * Diff embedded SBOMs across matched component pairs.
- */
-function diffEmbeddedSboms(pairs) {
-    const allDiffs = [];
-    for (const { oldComp, newComp } of pairs) {
-        if (!oldComp || !newComp)
-            continue;
-        const oldSbom = oldComp['sbom'];
-        const newSbom = newComp['sbom'];
-        if (!oldSbom || !newSbom)
-            continue;
-        if (typeof oldSbom !== 'object' || typeof newSbom !== 'object')
-            continue;
-        try {
-            const result = diffSboms(JSON.stringify(oldSbom), JSON.stringify(newSbom));
-            allDiffs.push(...result.packageDiffs);
-        }
-        catch {
-            // Skip SBOM diff if formats are incompatible
-        }
-    }
-    return allDiffs;
-}
-/**
- * Compute field-level changes for component or system fields.
- * Uses JSON Patch-like op/path format.
- */
-function computeComponentFieldChanges(oldObj, newObj, trackedFields) {
-    const changes = [];
-    for (const field of trackedFields) {
-        const oldVal = oldObj[field];
-        const newVal = newObj[field];
-        if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
-            if (oldVal === undefined && newVal !== undefined) {
-                changes.push({ op: 'add', path: field, newValue: newVal });
-            }
-            else if (oldVal !== undefined && newVal === undefined) {
-                changes.push({ op: 'remove', path: field, oldValue: oldVal });
-            }
-            else {
-                changes.push({ op: 'replace', path: field, oldValue: oldVal, newValue: newVal });
-            }
-        }
-    }
-    return changes;
-}
-//# sourceMappingURL=diff.js.map