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

package/dist/index.js

@@ -1,19 +1,2038 @@
-// Diff engine
-export { diffHdf, diffBaselines, diffSystems } from './diff.js';
-// Status utilities
-export { computeEffectiveStatus, classifyChangeReasons, classifyDiffStatus, } from './status.js';
-// Summary
-export { computeSummary } from './summary.js';
-// Normalization (v1 → v2)
-export { isV1Format, normalizeToV2 } from './normalize.js';
-// Matching strategies
-export { matchRequirements, createExactIdStrategy, createMappedIdStrategy, createCciMatchStrategy, createFuzzyTitleStrategy, tokenize, jaccardSimilarity, } from './matching/index.js';
-// Schema validation
-export { validateComparison } from './validate.js';
-// Exit codes
-export { EXIT_IDENTICAL, EXIT_DIFFERENCES, EXIT_ERROR, EXIT_DETAILED_IDENTICAL, EXIT_DETAILED_ERROR, EXIT_DETAILED_FIXES_ONLY, EXIT_DETAILED_REGRESSIONS_ONLY, EXIT_DETAILED_MIXED, EXIT_DETAILED_BASELINE_CHANGED, EXIT_DETAILED_DRIFT_ONLY, computeExitCode, computeDetailedExitCode, } from './exit-codes.js';
-// Renderers
-export { render, renderJson, renderMarkdown, renderTerminal, renderCsv } from './renderers/index.js';
-// SBOM comparison
-export { diffSboms } from './sbom.js';
+import { validateComparison as validateComparison$1 } from "@mitre/hdf-validators";
+//#region src/status.ts
+/** Status severity ranking — higher index = worse */
+const STATUS_SEVERITY = [
+	"notApplicable",
+	"notReviewed",
+	"passed",
+	"failed",
+	"error"
+];
+/** Statuses that count as "passing" for fixed/regressed classification */
+const PASSING_STATUSES = new Set(["passed"]);
+/** Statuses that count as "failing" for fixed/regressed classification */
+const FAILING_STATUSES = new Set([
+	"failed",
+	"error",
+	"notReviewed"
+]);
+/**
+* Determine the effective status of a requirement from its results and overrides.
+*
+* Priority:
+* 1. impact === 0 → notApplicable (regardless of results)
+* 2. effectiveStatus field set (and no statusOverrides) → use it
+* 3. Non-expired statusOverrides → use first non-expired
+* 4. Aggregate results using worst-wins
+* 5. Empty results → notReviewed
+*/
+function computeEffectiveStatus(requirement, referenceTimestamp) {
+	if (requirement["impact"] === 0) return "notApplicable";
+	const overrides = requirement["statusOverrides"];
+	if (overrides && overrides.length > 0) {
+		const refTime = referenceTimestamp ? new Date(referenceTimestamp).getTime() : Date.now();
+		for (const override of overrides) if (new Date(override.expiresAt).getTime() > refTime && override.status) return override.status;
+	}
+	const effectiveStatus = requirement["effectiveStatus"];
+	if (effectiveStatus && (!overrides || overrides.length === 0)) return effectiveStatus;
+	const results = requirement["results"];
+	if (!results || results.length === 0) return "notReviewed";
+	let worstIndex = -1;
+	let worstStatus = "notReviewed";
+	for (const result of results) {
+		const idx = STATUS_SEVERITY.indexOf(result.status);
+		if (idx > worstIndex) {
+			worstIndex = idx;
+			worstStatus = result.status;
+		}
+	}
+	return worstStatus;
+}
+/**
+* Classify why the status changed between two requirements.
+* Returns an array of change reasons (a status change can have multiple causes).
+*/
+function classifyChangeReasons(oldReq, newReq, oldTimestamp, newTimestamp) {
+	const reasons = [];
+	const oldResults = oldReq["results"] ?? [];
+	const newResults = newReq["results"] ?? [];
+	const oldResultStatuses = oldResults.map((r) => r.status).sort();
+	const newResultStatuses = newResults.map((r) => r.status).sort();
+	if (JSON.stringify(oldResultStatuses) !== JSON.stringify(newResultStatuses)) reasons.push("resultChanged");
+	const oldOverrides = oldReq["statusOverrides"] ?? [];
+	const newOverrides = newReq["statusOverrides"] ?? [];
+	if (newOverrides.length > oldOverrides.length) reasons.push("overrideAdded");
+	else if (newOverrides.length < oldOverrides.length) reasons.push("overrideRemoved");
+	if (oldTimestamp && newTimestamp && oldOverrides.length > 0) {
+		const oldTime = new Date(oldTimestamp).getTime();
+		const newTime = new Date(newTimestamp).getTime();
+		for (const override of oldOverrides) {
+			const expiresAt = new Date(override.expiresAt).getTime();
+			if (expiresAt > oldTime && expiresAt <= newTime) {
+				reasons.push("overrideExpired");
+				break;
+			}
+		}
+	}
+	if (oldReq["impact"] !== newReq["impact"]) reasons.push("impactChanged");
+	if (oldReq["disposition"] !== newReq["disposition"]) reasons.push("dispositionChanged");
+	if (oldReq["effectiveImpact"] !== newReq["effectiveImpact"]) reasons.push("effectiveImpactChanged");
+	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) reasons.push("metadataChanged");
+	return reasons;
+}
+/**
+* Classify the overall diff status based on old and new effective statuses.
+*
+* - If old is failing and new is passing → 'fixed'
+* - If old is passing and new is failing → 'regressed'
+* - If statuses are equal → 'unchanged'
+* - Otherwise → 'updated'
+*/
+function classifyDiffStatus(oldEffectiveStatus, newEffectiveStatus) {
+	if (oldEffectiveStatus === newEffectiveStatus) return "unchanged";
+	const oldIsFailing = FAILING_STATUSES.has(oldEffectiveStatus);
+	const newIsPassing = PASSING_STATUSES.has(newEffectiveStatus);
+	const oldIsPassing = PASSING_STATUSES.has(oldEffectiveStatus);
+	const newIsFailing = FAILING_STATUSES.has(newEffectiveStatus);
+	if (oldIsFailing && newIsPassing) return "fixed";
+	if (oldIsPassing && newIsFailing) return "regressed";
+	return "updated";
+}
+//#endregion
+//#region src/summary.ts
+/**
+* Compute summary counts from an array of RequirementDiff entries.
+*/
+function computeSummary(requirements) {
+	const summary = {
+		fixed: 0,
+		regressed: 0,
+		new: 0,
+		absent: 0,
+		unchanged: 0,
+		updated: 0,
+		total: requirements.length,
+		matchedCount: 0,
+		unmatchedOldCount: 0,
+		unmatchedNewCount: 0
+	};
+	for (const req of requirements) switch (req.state) {
+		case "fixed":
+			summary.fixed++;
+			summary.matchedCount++;
+			break;
+		case "regressed":
+			summary.regressed++;
+			summary.matchedCount++;
+			break;
+		case "new":
+			summary.new++;
+			summary.unmatchedNewCount++;
+			break;
+		case "absent":
+			summary.absent++;
+			summary.unmatchedOldCount++;
+			break;
+		case "unchanged":
+			summary.unchanged++;
+			summary.matchedCount++;
+			break;
+		case "updated":
+			summary.updated++;
+			summary.matchedCount++;
+			break;
+	}
+	return summary;
+}
+//#endregion
+//#region src/normalize.ts
+/**
+* Detect whether a document is v1 (InSpec exec-json) format.
+* V1 has `profiles` at the top level; v2 has `baselines`.
+*/
+function isV1Format(doc) {
+	return Array.isArray(doc["profiles"]) && !Array.isArray(doc["baselines"]);
+}
+/**
+* Normalize a document to v2-like structure. If already v2, returns as-is.
+* If v1, converts profiles→baselines, controls→requirements, and snake_case→camelCase.
+*/
+function normalizeToV2(doc) {
+	if (!isV1Format(doc)) return doc;
+	return {
+		baselines: doc["profiles"].map(normalizeProfile),
+		statistics: doc["statistics"],
+		timestamp: doc["timestamp"]
+	};
+}
+function normalizeProfile(profile) {
+	const requirements = (profile.controls ?? []).map(normalizeControl);
+	return {
+		name: profile.name,
+		title: profile.title,
+		version: profile.version,
+		checksum: profile.sha256 ? {
+			algorithm: "sha256",
+			value: profile.sha256
+		} : void 0,
+		groups: profile.groups ?? [],
+		supports: profile.supports ?? [],
+		inputs: profile.attributes ?? [],
+		requirements
+	};
+}
+function normalizeControl(control) {
+	const results = (control.results ?? []).map(normalizeResult);
+	return {
+		id: control.id,
+		title: control.title,
+		descriptions: control.desc ? [{
+			label: "default",
+			data: control.desc
+		}] : [],
+		impact: control.impact,
+		tags: control.tags ?? {},
+		refs: control.refs ?? [],
+		code: control.code,
+		sourceLocation: control.source_location ?? control.sourceLocation,
+		results
+	};
+}
+/**
+* Map InSpec v1 result status values to HDF v2 Result_Status enum values.
+*
+* InSpec v1 uses: "passed", "failed", "skipped", "error"
+* HDF v2 uses: "passed", "failed", "notApplicable", "notReviewed", "error"
+*
+* "skipped" in InSpec means the test was not executed (typically because a
+* `describe.one_of` condition was not met, or `only_if` excluded it).
+* This maps to "notReviewed" in HDF v2 — the requirement was not assessed.
+*/
+function normalizeResultStatus(v1Status) {
+	switch (v1Status) {
+		case "skipped": return "notReviewed";
+		default: return v1Status;
+	}
+}
+/**
+* Normalize a timestamp string to RFC 3339 / ISO 8601 date-time format.
+*
+* InSpec v1 uses formats like "2017-09-22 14:12:15 -0400" which are not valid
+* RFC 3339. This function attempts to parse and re-format such timestamps.
+* If parsing fails, the original string is returned as-is.
+*/
+function normalizeTimestamp(timestamp) {
+	if (timestamp.includes("T")) return timestamp;
+	const parsed = new Date(timestamp);
+	if (!isNaN(parsed.getTime())) return parsed.toISOString();
+	return timestamp;
+}
+function normalizeResult(result) {
+	const rawStartTime = result.start_time ?? result.startTime ?? "";
+	const normalized = {
+		status: normalizeResultStatus(result.status),
+		codeDesc: result.code_desc ?? result.codeDesc ?? "",
+		startTime: rawStartTime ? normalizeTimestamp(rawStartTime) : rawStartTime
+	};
+	const runTime = result.run_time ?? result.runTime;
+	if (runTime !== void 0) normalized["runTime"] = runTime;
+	if (result.message !== void 0) normalized["message"] = result.message;
+	return normalized;
+}
+//#endregion
+//#region src/matching/exact-id.ts
+/**
+* Create an exact ID matching strategy.
+*
+* Matches requirements by their `id` field with exact string equality.
+* Confidence is always 1.0 for matches.
+*/
+function createExactIdStrategy() {
+	return {
+		name: "exactId",
+		match(oldReqs, newReqs) {
+			const result = {
+				matched: [],
+				unmatchedOld: [],
+				unmatchedNew: []
+			};
+			const newById = /* @__PURE__ */ new Map();
+			const duplicateNewIds = /* @__PURE__ */ new Set();
+			for (const req of newReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (newById.has(id)) {
+						duplicateNewIds.add(id);
+						newById.delete(id);
+					} else if (!duplicateNewIds.has(id)) newById.set(id, req);
+				}
+			}
+			const oldById = /* @__PURE__ */ new Map();
+			const duplicateOldIds = /* @__PURE__ */ new Set();
+			for (const req of oldReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (oldById.has(id)) {
+						duplicateOldIds.add(id);
+						oldById.delete(id);
+					} else if (!duplicateOldIds.has(id)) oldById.set(id, req);
+				}
+			}
+			const matchedNewIds = /* @__PURE__ */ new Set();
+			for (const oldReq of oldReqs) {
+				const id = oldReq["id"];
+				if (typeof id !== "string" || duplicateOldIds.has(id)) {
+					result.unmatchedOld.push(oldReq);
+					continue;
+				}
+				const newReq = newById.get(id);
+				if (newReq) {
+					result.matched.push({
+						oldReq,
+						newReq,
+						strategy: "exactId",
+						confidence: 1
+					});
+					matchedNewIds.add(id);
+				} else result.unmatchedOld.push(oldReq);
+			}
+			for (const req of newReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (duplicateNewIds.has(id) || !matchedNewIds.has(id)) result.unmatchedNew.push(req);
+				} else result.unmatchedNew.push(req);
+			}
+			return result;
+		}
+	};
+}
+//#endregion
+//#region src/matching/mapped-id.ts
+/**
+* Create a mapped ID matching strategy.
+*
+* Translates old requirement IDs using a mapping table before matching.
+* Only matches requirements whose old ID appears in the mapping table and
+* whose mapped new ID exists in the new requirements.
+*
+* Confidence is 0.95 for mapped matches (slightly less than exact ID
+* because the match depends on the accuracy of the mapping table).
+*/
+function createMappedIdStrategy(mapping) {
+	return {
+		name: "mappedId",
+		match(oldReqs, newReqs) {
+			const result = {
+				matched: [],
+				unmatchedOld: [],
+				unmatchedNew: []
+			};
+			const newById = /* @__PURE__ */ new Map();
+			const duplicateNewIds = /* @__PURE__ */ new Set();
+			for (const req of newReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (newById.has(id)) {
+						duplicateNewIds.add(id);
+						newById.delete(id);
+					} else if (!duplicateNewIds.has(id)) newById.set(id, req);
+				}
+			}
+			const oldById = /* @__PURE__ */ new Map();
+			const duplicateOldIds = /* @__PURE__ */ new Set();
+			for (const req of oldReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (oldById.has(id)) {
+						duplicateOldIds.add(id);
+						oldById.delete(id);
+					} else if (!duplicateOldIds.has(id)) oldById.set(id, req);
+				}
+			}
+			const matchedNewIds = /* @__PURE__ */ new Set();
+			for (const oldReq of oldReqs) {
+				const oldId = oldReq["id"];
+				if (typeof oldId !== "string" || duplicateOldIds.has(oldId)) {
+					result.unmatchedOld.push(oldReq);
+					continue;
+				}
+				const mappedNewId = mapping[oldId];
+				if (mappedNewId === void 0) {
+					result.unmatchedOld.push(oldReq);
+					continue;
+				}
+				if (duplicateNewIds.has(mappedNewId)) {
+					result.unmatchedOld.push(oldReq);
+					continue;
+				}
+				const newReq = newById.get(mappedNewId);
+				if (newReq && !matchedNewIds.has(mappedNewId)) {
+					result.matched.push({
+						oldReq,
+						newReq,
+						strategy: "mappedId",
+						confidence: .95
+					});
+					matchedNewIds.add(mappedNewId);
+				} else result.unmatchedOld.push(oldReq);
+			}
+			for (const req of newReqs) {
+				const id = req["id"];
+				if (typeof id === "string") {
+					if (duplicateNewIds.has(id) || !matchedNewIds.has(id)) result.unmatchedNew.push(req);
+				} else result.unmatchedNew.push(req);
+			}
+			return result;
+		}
+	};
+}
+//#endregion
+//#region src/matching/cci-match.ts
+/**
+* Extract CCI identifiers from a requirement's tags.
+* Looks for `tags.cci` as an array of strings.
+*/
+function extractCcis(req) {
+	const tags = req["tags"];
+	if (!tags) return [];
+	const cci = tags["cci"];
+	if (!Array.isArray(cci)) return [];
+	return cci.filter((c) => typeof c === "string");
+}
+/**
+* Create a CCI-based matching strategy.
+*
+* Matches requirements that share the same CCI identifier in `tags.cci`.
+* Only produces a match when exactly one old requirement and exactly one
+* new requirement share a given CCI (unambiguous). Ambiguous CCIs (shared
+* by multiple old or multiple new requirements) are skipped, and those
+* requirements are left unmatched.
+*
+* Confidence is 0.8 for unambiguous matches.
+*/
+function createCciMatchStrategy() {
+	return {
+		name: "cciMatch",
+		match(oldReqs, newReqs) {
+			const result = {
+				matched: [],
+				unmatchedOld: [],
+				unmatchedNew: []
+			};
+			const oldCciMap = /* @__PURE__ */ new Map();
+			for (let i = 0; i < oldReqs.length; i++) for (const cci of extractCcis(oldReqs[i])) {
+				const list = oldCciMap.get(cci);
+				if (list) list.push(i);
+				else oldCciMap.set(cci, [i]);
+			}
+			const newCciMap = /* @__PURE__ */ new Map();
+			for (let i = 0; i < newReqs.length; i++) for (const cci of extractCcis(newReqs[i])) {
+				const list = newCciMap.get(cci);
+				if (list) list.push(i);
+				else newCciMap.set(cci, [i]);
+			}
+			const matchedOldIndices = /* @__PURE__ */ new Set();
+			const matchedNewIndices = /* @__PURE__ */ new Set();
+			const allCcis = new Set([...oldCciMap.keys(), ...newCciMap.keys()]);
+			for (const cci of allCcis) {
+				const oldIndices = oldCciMap.get(cci) ?? [];
+				const newIndices = newCciMap.get(cci) ?? [];
+				if (oldIndices.length !== 1 || newIndices.length !== 1) continue;
+				const oldIdx = oldIndices[0];
+				const newIdx = newIndices[0];
+				if (matchedOldIndices.has(oldIdx) || matchedNewIndices.has(newIdx)) continue;
+				result.matched.push({
+					oldReq: oldReqs[oldIdx],
+					newReq: newReqs[newIdx],
+					strategy: "cciMatch",
+					confidence: .8
+				});
+				matchedOldIndices.add(oldIdx);
+				matchedNewIndices.add(newIdx);
+			}
+			for (let i = 0; i < oldReqs.length; i++) if (!matchedOldIndices.has(i)) result.unmatchedOld.push(oldReqs[i]);
+			for (let i = 0; i < newReqs.length; i++) if (!matchedNewIndices.has(i)) result.unmatchedNew.push(newReqs[i]);
+			return result;
+		}
+	};
+}
+//#endregion
+//#region src/matching/fuzzy-match.ts
+/** Common English stop words to exclude from tokenization */
+const STOP_WORDS = new Set([
+	"a",
+	"an",
+	"the",
+	"is",
+	"are",
+	"was",
+	"were",
+	"be",
+	"been",
+	"being",
+	"have",
+	"has",
+	"had",
+	"do",
+	"does",
+	"did",
+	"will",
+	"would",
+	"could",
+	"should",
+	"may",
+	"might",
+	"shall",
+	"can",
+	"to",
+	"of",
+	"in",
+	"for",
+	"on",
+	"with",
+	"at",
+	"by",
+	"from",
+	"as",
+	"into",
+	"through",
+	"during",
+	"before",
+	"after",
+	"above",
+	"below",
+	"between",
+	"out",
+	"off",
+	"over",
+	"under",
+	"again",
+	"further",
+	"then",
+	"once",
+	"and",
+	"but",
+	"or",
+	"nor",
+	"not",
+	"no",
+	"so",
+	"if",
+	"it",
+	"its",
+	"that",
+	"this",
+	"these",
+	"those",
+	"each",
+	"every",
+	"all",
+	"both",
+	"few",
+	"more",
+	"most",
+	"other",
+	"some",
+	"such",
+	"than",
+	"too",
+	"very",
+	"just",
+	"about"
+]);
+/**
+* Tokenize a title string into a set of meaningful tokens.
+*
+* - Lowercases the string
+* - Splits on whitespace and punctuation
+* - Filters out common stop words
+* - Returns unique tokens as a Set
+*/
+function tokenize(text) {
+	if (!text) return /* @__PURE__ */ new Set();
+	const tokens = text.toLowerCase().split(/[\s\-_/\\,.;:!?()[\]{}"']+/).filter((t) => t.length > 0 && !STOP_WORDS.has(t));
+	return new Set(tokens);
+}
+/**
+* Compute Jaccard similarity between two sets.
+* Returns |intersection| / |union|, or 0 if both sets are empty.
+*/
+function jaccardSimilarity(a, b) {
+	if (a.size === 0 && b.size === 0) return 0;
+	let intersectionSize = 0;
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const item of smaller) if (larger.has(item)) intersectionSize++;
+	const unionSize = a.size + b.size - intersectionSize;
+	/* c8 ignore next */
+	if (unionSize === 0) return 0;
+	return intersectionSize / unionSize;
+}
+/**
+* Default minimum confidence threshold for fuzzy title matching.
+*/
+const DEFAULT_MIN_CONFIDENCE = .6;
+/**
+* Create a fuzzy title matching strategy.
+*
+* Matches requirements by token-based Jaccard similarity on the `title` field.
+* Uses greedy best-match: for each unmatched old requirement, finds the
+* best-matching unmatched new requirement above the confidence threshold.
+*
+* @param minConfidence Minimum Jaccard similarity to accept a match (default: 0.6)
+*/
+function createFuzzyTitleStrategy(minConfidence) {
+	const threshold = minConfidence ?? DEFAULT_MIN_CONFIDENCE;
+	return {
+		name: "fuzzyTitle",
+		match(oldReqs, newReqs) {
+			const result = {
+				matched: [],
+				unmatchedOld: [],
+				unmatchedNew: []
+			};
+			const oldTokens = [];
+			for (let i = 0; i < oldReqs.length; i++) {
+				const title = oldReqs[i]["title"];
+				if (typeof title === "string" && title.length > 0) {
+					const tokens = tokenize(title);
+					if (tokens.size > 0) oldTokens.push({
+						idx: i,
+						tokens
+					});
+				}
+			}
+			const newTokens = [];
+			for (let i = 0; i < newReqs.length; i++) {
+				const title = newReqs[i]["title"];
+				if (typeof title === "string" && title.length > 0) {
+					const tokens = tokenize(title);
+					if (tokens.size > 0) newTokens.push({
+						idx: i,
+						tokens
+					});
+				}
+			}
+			const matchedOldIndices = /* @__PURE__ */ new Set();
+			const matchedNewIndices = /* @__PURE__ */ new Set();
+			const candidates = [];
+			for (const old of oldTokens) for (const nw of newTokens) {
+				const sim = jaccardSimilarity(old.tokens, nw.tokens);
+				if (sim >= threshold) candidates.push({
+					oldIdx: old.idx,
+					newIdx: nw.idx,
+					similarity: sim
+				});
+			}
+			candidates.sort((a, b) => b.similarity - a.similarity);
+			for (const candidate of candidates) {
+				if (matchedOldIndices.has(candidate.oldIdx) || matchedNewIndices.has(candidate.newIdx)) continue;
+				result.matched.push({
+					oldReq: oldReqs[candidate.oldIdx],
+					newReq: newReqs[candidate.newIdx],
+					strategy: "fuzzyTitle",
+					confidence: candidate.similarity
+				});
+				matchedOldIndices.add(candidate.oldIdx);
+				matchedNewIndices.add(candidate.newIdx);
+			}
+			for (let i = 0; i < oldReqs.length; i++) if (!matchedOldIndices.has(i)) result.unmatchedOld.push(oldReqs[i]);
+			for (let i = 0; i < newReqs.length; i++) if (!matchedNewIndices.has(i)) result.unmatchedNew.push(newReqs[i]);
+			return result;
+		}
+	};
+}
+//#endregion
+//#region src/matching/index.ts
+/**
+* Create a strategy instance by name, using the provided options for
+* strategies that require configuration.
+*/
+function createStrategy(name, options) {
+	switch (name) {
+		case "exactId": return createExactIdStrategy();
+		case "mappedId": return createMappedIdStrategy(options.mappingTable ?? {});
+		case "cciMatch": return createCciMatchStrategy();
+		case "fuzzyTitle": return createFuzzyTitleStrategy(options.minConfidence);
+		default: throw new Error(`Unknown matching strategy: '${name}'`);
+	}
+}
+/**
+* Match requirements between two evaluations using a primary strategy
+* and optional fallback strategies.
+*
+* The registry applies strategies in order:
+* 1. Primary strategy matches what it can
+* 2. Unmatched requirements pass to the next fallback strategy
+* 3. Process continues until all strategies are exhausted or all
+*    requirements are matched
+*
+* @param oldReqs Requirements from the old evaluation
+* @param newReqs Requirements from the new evaluation
+* @param options Matching configuration
+* @returns Combined match result from all strategies
+*/
+function matchRequirements(oldReqs, newReqs, options) {
+	const opts = options ?? {};
+	const strategies = [opts.strategy ?? "exactId", ...opts.fallbackStrategies ?? []].map((name) => createStrategy(name, opts));
+	const allMatched = [];
+	let currentUnmatchedOld = oldReqs;
+	let currentUnmatchedNew = newReqs;
+	for (const strategy of strategies) {
+		if (currentUnmatchedOld.length === 0 || currentUnmatchedNew.length === 0) break;
+		const result = strategy.match(currentUnmatchedOld, currentUnmatchedNew);
+		allMatched.push(...result.matched);
+		currentUnmatchedOld = result.unmatchedOld;
+		currentUnmatchedNew = result.unmatchedNew;
+	}
+	return {
+		matched: allMatched,
+		unmatchedOld: currentUnmatchedOld,
+		unmatchedNew: currentUnmatchedNew
+	};
+}
+//#endregion
+//#region src/validate.ts
+/**
+* Validate a document against the hdf-comparison schema.
+*
+* Delegates to @mitre/hdf-validators which loads schemas from embedded
+* bundled JSON (no filesystem access, no hardcoded version URLs).
+*
+* @param doc - The document to validate (typically the output of `diffHdf()`)
+* @returns Validation result with `valid` boolean and optional `errors` array
+*/
+function validateComparison(doc) {
+	const result = validateComparison$1(doc);
+	if (result.valid) return { valid: true };
+	return {
+		valid: false,
+		errors: result.errors.map((e) => e.field === "(root)" ? e.message : `${e.field}: ${e.message}`)
+	};
+}
+//#endregion
+//#region src/sbom.ts
+/**
+* Compare two SBOM documents (CycloneDX or SPDX JSON strings) and return
+* package-level diffs.
+*
+* @param oldJson - JSON string of the old SBOM document
+* @param newJson - JSON string of the new SBOM document
+* @returns Structured diff result with per-package state and aggregate counts
+* @throws Error if either input is not valid JSON or not a recognized SBOM format
+*/
+function diffSboms(oldJson, newJson) {
+	const oldParsed = JSON.parse(oldJson);
+	const newParsed = JSON.parse(newJson);
+	const oldPackages = extractPackages(oldParsed);
+	const newPackages = extractPackages(newParsed);
+	const oldMap = buildPackageMap(oldPackages);
+	const newMap = buildPackageMap(newPackages);
+	const diffs = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const [key, oldPkg] of oldMap) {
+		seen.add(key);
+		const newPkg = newMap.get(key);
+		if (newPkg) if (oldPkg.version !== newPkg.version) diffs.push({
+			purl: newPkg.purl || newPkg.name,
+			name: newPkg.name,
+			state: "updated",
+			oldVersion: oldPkg.version,
+			newVersion: newPkg.version,
+			licenses: newPkg.licenses.length > 0 ? newPkg.licenses : void 0
+		});
+		else diffs.push({
+			purl: oldPkg.purl || oldPkg.name,
+			name: oldPkg.name,
+			state: "unchanged"
+		});
+		else diffs.push({
+			purl: oldPkg.purl || oldPkg.name,
+			name: oldPkg.name,
+			state: "removed",
+			oldVersion: oldPkg.version
+		});
+	}
+	for (const [key, newPkg] of newMap) if (!seen.has(key)) diffs.push({
+		purl: newPkg.purl || newPkg.name,
+		name: newPkg.name,
+		state: "added",
+		newVersion: newPkg.version,
+		licenses: newPkg.licenses.length > 0 ? newPkg.licenses : void 0
+	});
+	diffs.sort((a, b) => a.name.localeCompare(b.name));
+	let added = 0;
+	let removed = 0;
+	let updated = 0;
+	let unchanged = 0;
+	for (const d of diffs) switch (d.state) {
+		case "added":
+			added++;
+			break;
+		case "removed":
+			removed++;
+			break;
+		case "updated":
+			updated++;
+			break;
+		case "unchanged":
+			unchanged++;
+			break;
+	}
+	return {
+		packageDiffs: diffs,
+		added,
+		removed,
+		updated,
+		unchanged
+	};
+}
+/**
+* Extract packages from an SBOM document, auto-detecting the format.
+*/
+function extractPackages(doc) {
+	if (doc["bomFormat"] === "CycloneDX") return extractCycloneDXPackages(doc);
+	if (typeof doc["spdxVersion"] === "string") return extractSPDXPackages(doc);
+	throw new Error("Unrecognized SBOM format: expected CycloneDX (bomFormat) or SPDX (spdxVersion)");
+}
+/**
+* Extract packages from a CycloneDX document.
+* Reads components[] with purl, name, version fields.
+*/
+function extractCycloneDXPackages(doc) {
+	const components = doc["components"];
+	if (!Array.isArray(components)) return [];
+	return components.map((comp) => {
+		const licenses = extractCycloneDXLicenses(comp);
+		return {
+			purl: comp["purl"] ?? "",
+			name: comp["name"] ?? "",
+			version: comp["version"] ?? "",
+			licenses
+		};
+	});
+}
+/**
+* Extract license strings from a CycloneDX component.
+* CycloneDX licenses can be in `licenses[].license.id` or `licenses[].license.name`.
+*/
+function extractCycloneDXLicenses(comp) {
+	const licensesArr = comp["licenses"];
+	if (!Array.isArray(licensesArr)) return [];
+	const result = [];
+	for (const entry of licensesArr) {
+		const license = entry["license"];
+		if (license) {
+			const id = license["id"];
+			const name = license["name"];
+			if (id) result.push(id);
+			else if (name) result.push(name);
+		}
+	}
+	return result;
+}
+/**
+* Extract packages from an SPDX document.
+* Reads packages[] with name, versionInfo, and externalRefs (for PURL).
+*/
+function extractSPDXPackages(doc) {
+	const packages = doc["packages"];
+	if (!Array.isArray(packages)) return [];
+	return packages.map((pkg) => {
+		const purl = extractSPDXPurl(pkg);
+		const license = pkg["licenseConcluded"] ?? pkg["licenseDeclared"] ?? "";
+		return {
+			purl,
+			name: pkg["name"] ?? "",
+			version: pkg["versionInfo"] ?? "",
+			licenses: license && license !== "NOASSERTION" ? [license] : []
+		};
+	});
+}
+/**
+* Extract a PURL from an SPDX package's externalRefs array.
+*/
+function extractSPDXPurl(pkg) {
+	const refs = pkg["externalRefs"];
+	if (!Array.isArray(refs)) return "";
+	for (const ref of refs) if (ref["referenceType"] === "purl") return ref["referenceLocator"] ?? "";
+	return "";
+}
+/**
+* Build a lookup map of packages indexed by name (version-independent key).
+*/
+function buildPackageMap(packages) {
+	const map = /* @__PURE__ */ new Map();
+	for (const pkg of packages) {
+		const key = pkg.name || pkg.purl;
+		if (key) map.set(key, pkg);
+	}
+	return map;
+}
+//#endregion
+//#region src/diff.ts
+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"];
+}
+/**
+* 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).
+*/
+function diffHdf(oldResults, newResults, options) {
+	const trackedFields = options?.trackedFields ?? DEFAULT_TRACKED_FIELDS;
+	let comparisonMode = options?.comparisonMode ?? "temporal";
+	const matchOpts = buildMatchOptions(options);
+	if (!options?.comparisonMode && !Array.isArray(newResults)) {
+		if (isBaselineDocument(oldResults) && isBaselineDocument(newResults)) comparisonMode = "baselineEvolution";
+		else if (isSystemDocument(oldResults) && isSystemDocument(newResults)) comparisonMode = "systemDrift";
+	}
+	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.`);
+	}
+	if (comparisonMode === "baselineEvolution") return diffBaselines(oldResults, Array.isArray(newResults) ? newResults[0] : newResults, options);
+	if (comparisonMode === "systemDrift") return diffSystems(oldResults, Array.isArray(newResults) ? newResults[0] : newResults, options);
+	if (comparisonMode === "fleet") return diffFleet(oldResults, newResults, trackedFields, matchOpts);
+	const newDoc = Array.isArray(newResults) ? newResults[0] : newResults;
+	const oldNormalized = normalizeToV2(oldResults);
+	const newNormalized = normalizeToV2(newDoc);
+	const oldTimestamp = oldNormalized["timestamp"];
+	const newTimestamp = newNormalized["timestamp"];
+	const sources = buildSources(comparisonMode, oldResults, newDoc, oldTimestamp, newTimestamp);
+	const { baselineDiffs, requirementDiffs } = comparePair(oldNormalized, newNormalized, oldTimestamp, newTimestamp, trackedFields, matchOpts);
+	requirementDiffs.sort((a, b) => a.id.localeCompare(b.id));
+	const drift = extractDrift(requirementDiffs);
+	const comparison = {
+		formatVersion: "1.0.0",
+		comparisonMode,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		sources,
+		matching: { primaryStrategy: resolveStrategyName(options) },
+		summary: computeSummary(requirementDiffs),
+		baselineDiffs,
+		requirementDiffs,
+		drift
+	};
+	if (options?.validateOutput) {
+		const result = validateComparison(comparison);
+		/* c8 ignore start */
+		if (!result.valid) throw new Error(`Output validation failed: ${result.errors?.join(", ")}`);
+	}
+	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
+			}];
+		}
+		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"];
+	const sources = [{
+		role: "reference",
+		label: "Reference",
+		assessmentTimestamp: refTimestamp
+	}];
+	const allRequirementDiffs = [];
+	const allBaselineDiffs = [];
+	const seenBaselineNames = /* @__PURE__ */ new Set();
+	for (let i = 0; i < systems.length; i++) {
+		const sysNormalized = normalizeToV2(systems[i]);
+		const sysTimestamp = sysNormalized["timestamp"];
+		const sourceIndex = i + 1;
+		sources.push({
+			role: "system",
+			label: `System ${sourceIndex}`,
+			assessmentTimestamp: sysTimestamp
+		});
+		const { baselineDiffs, requirementDiffs } = comparePair(refNormalized, sysNormalized, refTimestamp, sysTimestamp, trackedFields, matchOpts);
+		for (const rd of requirementDiffs) {
+			rd.sourceIndex = sourceIndex;
+			allRequirementDiffs.push(rd);
+		}
+		for (const bd of baselineDiffs) if (!seenBaselineNames.has(bd.name)) {
+			seenBaselineNames.add(bd.name);
+			allBaselineDiffs.push(bd);
+		}
+	}
+	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);
+	});
+	const drift = extractDrift(allRequirementDiffs);
+	return {
+		formatVersion: "1.0.0",
+		comparisonMode: "fleet",
+		timestamp: (/* @__PURE__ */ 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"] ?? [];
+	const oldBaselineMap = /* @__PURE__ */ new Map();
+	for (const b of oldBaselines) oldBaselineMap.set(b.name, b);
+	const newBaselineMap = /* @__PURE__ */ new Map();
+	for (const b of newBaselines) newBaselineMap.set(b.name, b);
+	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"
+		});
+	}
+	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);
+	const matchResult = matchRequirements(oldReqs, newReqs, matchOpts);
+	const requirementDiffs = [];
+	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
+		});
+	}
+	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
+		});
+	}
+	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];
+		if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) if (oldVal === void 0 && newVal !== void 0) changes.push({
+			op: "add",
+			path: field,
+			newValue: newVal
+		});
+		else if (oldVal !== void 0 && newVal === void 0) 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"] === void 0;
+}
+/** 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.
+*/
+function diffBaselines(oldBaseline, newBaseline, options) {
+	const trackedFields = options?.trackedFields ?? BASELINE_TRACKED_FIELDS;
+	const matchOpts = buildMatchOptions(options);
+	const matchResult = matchRequirements(oldBaseline["requirements"] ?? [], newBaseline["requirements"] ?? [], matchOpts);
+	const requirementDiffs = [];
+	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);
+		const state = fieldChanges.length > 0 ? "updated" : "unchanged";
+		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
+		});
+	}
+	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
+		});
+	}
+	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
+		});
+	}
+	requirementDiffs.sort((a, b) => a.id.localeCompare(b.id));
+	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"
+		});
+	}
+	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: (/* @__PURE__ */ 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(", ")}`);
+	}
+	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"] === void 0;
+}
+/** 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.
+*/
+function diffSystems(oldSystem, newSystem, options) {
+	const pairs = matchComponents(oldSystem["components"] ?? [], newSystem["components"] ?? []);
+	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));
+	const systemFieldChanges = computeComponentFieldChanges(oldSystem, newSystem, SYSTEM_TOP_LEVEL_FIELDS);
+	const counts = {
+		new: 0,
+		absent: 0,
+		unchanged: 0,
+		updated: 0
+	};
+	for (const cd of componentDiffs) counts[cd.state]++;
+	const oldName = oldSystem["name"] ?? "";
+	const systemName = (newSystem["name"] ?? "") || 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: (/* @__PURE__ */ 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
+	};
+	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;
+	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(", ")}`);
+	}
+	return comparison;
+}
+/**
+* Match old and new components by componentId (when available) or name.
+*/
+function matchComponents(oldComponents, newComponents) {
+	const matched = /* @__PURE__ */ new Set();
+	const pairs = [];
+	const newById = /* @__PURE__ */ new Map();
+	for (let i = 0; i < newComponents.length; i++) {
+		const id = newComponents[i]["componentId"];
+		if (id) newById.set(id, i);
+	}
+	const oldMatched = /* @__PURE__ */ 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);
+		}
+	}
+	const newByName = /* @__PURE__ */ 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);
+		}
+	}
+	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: void 0
+		});
+	}
+	for (let i = 0; i < newComponents.length; i++) {
+		if (matched.has(i)) continue;
+		const name = newComponents[i]["name"] || `component-${i}`;
+		pairs.push({
+			name,
+			oldComp: void 0,
+			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) => {
+		return `${f["from"] ?? ""}→${typeof f["to"] === "string" ? f["to"] : JSON.stringify(f["to"])}`;
+	};
+	const oldMap = /* @__PURE__ */ new Map();
+	for (const f of oldFlows) oldMap.set(flowKey(f), f);
+	const newMap = /* @__PURE__ */ 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 {}
+	}
+	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 === void 0 && newVal !== void 0) changes.push({
+			op: "add",
+			path: field,
+			newValue: newVal
+		});
+		else if (oldVal !== void 0 && newVal === void 0) changes.push({
+			op: "remove",
+			path: field,
+			oldValue: oldVal
+		});
+		else changes.push({
+			op: "replace",
+			path: field,
+			oldValue: oldVal,
+			newValue: newVal
+		});
+	}
+	return changes;
+}
+//#endregion
+//#region src/exit-codes.ts
+/** GNU diff compatible exit codes (--exit-code mode) */
+const EXIT_IDENTICAL = 0;
+const EXIT_DIFFERENCES = 1;
+const EXIT_ERROR = 2;
+/** Detailed exit codes (--detailed-exitcode mode) */
+const EXIT_DETAILED_IDENTICAL = 0;
+const EXIT_DETAILED_ERROR = 1;
+const EXIT_DETAILED_FIXES_ONLY = 10;
+const EXIT_DETAILED_REGRESSIONS_ONLY = 11;
+const EXIT_DETAILED_MIXED = 12;
+const EXIT_DETAILED_BASELINE_CHANGED = 13;
+const EXIT_DETAILED_DRIFT_ONLY = 14;
+/**
+* Compute the GNU diff compatible exit code from a comparison summary.
+*
+* Returns:
+*   0 = identical (no differences found)
+*   1 = differences found (any kind)
+*
+* Note: error (exit code 2) is not computed from the summary — callers
+* should return EXIT_ERROR directly when I/O or parse errors occur.
+*/
+function computeExitCode(summary) {
+	if (hasDifferences(summary)) return 1;
+	return 0;
+}
+/**
+* Compute the detailed exit code from a comparison summary.
+*
+* Returns:
+*   0  = identical (no differences found)
+*   10 = differences found, fixes only (security posture improved)
+*   11 = differences found, regressions only (security posture degraded)
+*   12 = differences found, mixed fixes and regressions
+*   13 = differences found, only new/absent controls (baseline changed)
+*   14 = differences found, only metadata drift (no status changes)
+*
+* Note: error (exit code 1) is not computed from the summary — callers
+* should return EXIT_DETAILED_ERROR directly when I/O or parse errors occur.
+*
+* Priority order: mixed(12) > regressions(11) > fixes(10) > baseline(13) > drift(14)
+*/
+function computeDetailedExitCode(summary) {
+	if (!hasDifferences(summary)) return 0;
+	if (summary.regressed > 0 && summary.fixed > 0) return 12;
+	if (summary.regressed > 0) return 11;
+	if (summary.fixed > 0) return 10;
+	if (summary.new > 0 || summary.absent > 0) return 13;
+	return 14;
+}
+/**
+* Returns true if the summary indicates any differences at all.
+*/
+function hasDifferences(summary) {
+	return summary.total !== summary.unchanged;
+}
+//#endregion
+//#region src/renderers/filter.ts
+/**
+* Filter requirement diffs based on render options.
+*
+* Supports filtering by:
+* - `filterStates`: Only include requirements matching the given states
+* - `filterSeverity`: Only include requirements matching the given severity tag
+*/
+function filterRequirements(diffs, options) {
+	let filtered = diffs;
+	if (options?.filterStates && options.filterStates.length > 0) {
+		const states = new Set(options.filterStates);
+		filtered = filtered.filter((r) => states.has(r.state));
+	}
+	if (options?.filterSeverity) {
+		const severity = options.filterSeverity.toLowerCase();
+		filtered = filtered.filter((r) => {
+			const before = r.before;
+			const tags = r.after?.["tags"] ?? before?.["tags"];
+			if (!tags) return false;
+			return typeof tags["severity"] === "string" && tags["severity"].toLowerCase() === severity;
+		});
+	}
+	return filtered;
+}
+//#endregion
+//#region src/renderers/json.ts
+/**
+* Strip `before` and `after` from a RequirementDiff, keeping only
+* the summary fields (id, state, title, statuses, changeReasons, fieldChanges).
+*/
+function stripSnapshots(req) {
+	const { before, after, ...rest } = req;
+	return rest;
+}
+/**
+* Render an HdfComparison as a JSON string.
+*
+* - `detail: 'summary'` -- only `{ formatVersion, comparisonMode, summary }`
+* - `detail: 'control'` -- full document but `before`/`after` stripped from requirementDiffs
+* - `detail: 'full'`    -- `JSON.stringify(comparison, null, 2)` (the complete document)
+*
+* Default detail level: `'control'`.
+*/
+function renderJson(comparison, options) {
+	const detail = options?.detail ?? "control";
+	if (detail === "summary") return JSON.stringify({
+		formatVersion: comparison.formatVersion,
+		comparisonMode: comparison.comparisonMode,
+		summary: comparison.summary
+	}, null, 2);
+	if (detail === "full") {
+		const filtered = filterRequirements(comparison.requirementDiffs, options);
+		if (filtered.length !== comparison.requirementDiffs.length) return JSON.stringify({
+			...comparison,
+			requirementDiffs: filtered
+		}, null, 2);
+		return JSON.stringify(comparison, null, 2);
+	}
+	const strippedDiffs = filterRequirements(comparison.requirementDiffs, options).map(stripSnapshots);
+	return JSON.stringify({
+		...comparison,
+		requirementDiffs: strippedDiffs
+	}, null, 2);
+}
+//#endregion
+//#region src/renderers/markdown.ts
+/**
+* Render the summary table in markdown format.
+*/
+function renderSummaryTable(comparison) {
+	const { summary } = comparison;
+	return [
+		"## HDF Comparison Summary",
+		"",
+		"| Metric | Count |",
+		"|--------|-------|",
+		`| Fixed | ${summary.fixed} |`,
+		`| Regressed | ${summary.regressed} |`,
+		`| New | ${summary.new} |`,
+		`| Absent | ${summary.absent} |`,
+		`| Unchanged | ${summary.unchanged} |`,
+		`| Updated | ${summary.updated} |`,
+		`| **Total** | **${summary.total}** |`
+	].join("\n");
+}
+/**
+* Group requirement diffs by state.
+*/
+function groupByState(diffs) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const diff of diffs) {
+		const existing = groups.get(diff.state);
+		if (existing) existing.push(diff);
+		else groups.set(diff.state, [diff]);
+	}
+	return groups;
+}
+/**
+* Escape a value for use in a markdown table cell.
+* Replaces pipe characters with their HTML entity.
+*/
+function escapeCell(value) {
+	return value.replace(/\|/g, "&#124;");
+}
+/**
+* Format field changes for a markdown cell.
+*/
+function formatFieldChanges$1(req) {
+	if (req.fieldChanges.length === 0) return "";
+	return req.fieldChanges.map((fc) => {
+		if (fc.op === "add") return `+${fc.path}: ${JSON.stringify(fc.newValue)}`;
+		if (fc.op === "remove") return `-${fc.path}: ${JSON.stringify(fc.oldValue)}`;
+		return `${fc.path}: ${JSON.stringify(fc.oldValue)} -> ${JSON.stringify(fc.newValue)}`;
+	}).join("; ");
+}
+/**
+* Render a section for a single state group.
+*/
+function renderStateSection(state, diffs, detail) {
+	const lines = [`### ${state.charAt(0).toUpperCase() + state.slice(1)} (${diffs.length})`];
+	if (diffs.length === 0) {
+		lines.push("", "(none)");
+		return lines.join("\n");
+	}
+	lines.push("");
+	if (detail === "full") {
+		lines.push("| ID | Title | Old Status | New Status | Change Reasons | Field Changes |", "|----|-------|------------|------------|----------------|---------------|");
+		for (const req of diffs) {
+			const id = escapeCell(req.id);
+			const title = escapeCell(req.title ?? "");
+			const oldStatus = escapeCell(req.oldEffectiveStatus ?? "");
+			const newStatus = escapeCell(req.newEffectiveStatus ?? "");
+			const reasons = escapeCell(req.changeReasons.join(", "));
+			const fieldChanges = escapeCell(formatFieldChanges$1(req));
+			lines.push(`| ${id} | ${title} | ${oldStatus} | ${newStatus} | ${reasons} | ${fieldChanges} |`);
+		}
+	} else {
+		lines.push("| ID | Title | Old Status | New Status |", "|----|-------|------------|------------|");
+		for (const req of diffs) {
+			const id = escapeCell(req.id);
+			const title = escapeCell(req.title ?? "");
+			const oldStatus = escapeCell(req.oldEffectiveStatus ?? "");
+			const newStatus = escapeCell(req.newEffectiveStatus ?? "");
+			lines.push(`| ${id} | ${title} | ${oldStatus} | ${newStatus} |`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Render an HdfComparison as a Markdown string.
+*
+* - `detail: 'summary'` -- summary table only
+* - `detail: 'control'` -- summary + per-requirement tables by state
+* - `detail: 'full'`    -- summary + per-requirement tables with changeReasons and fieldChanges
+*
+* Default detail level: `'control'`.
+*/
+function renderMarkdown(comparison, options) {
+	const detail = options?.detail ?? "control";
+	const parts = [renderSummaryTable(comparison)];
+	if (detail === "summary") return parts.join("\n");
+	const stateOrder = [
+		"fixed",
+		"regressed",
+		"new",
+		"absent",
+		"updated",
+		"unchanged"
+	];
+	const grouped = groupByState(filterRequirements(comparison.requirementDiffs, options));
+	const statesToShow = options?.filterStates && options.filterStates.length > 0 ? stateOrder.filter((s) => options.filterStates.includes(s)) : stateOrder;
+	for (const state of statesToShow) {
+		parts.push("");
+		const diffs = grouped.get(state) ?? [];
+		parts.push(renderStateSection(state, diffs, detail));
+	}
+	return parts.join("\n");
+}
+//#endregion
+//#region src/renderers/terminal.ts
+const RESET = "\x1B[0m";
+const GREEN = "\x1B[32m";
+const RED = "\x1B[31m";
+const YELLOW = "\x1B[33m";
+const BOLD = "\x1B[1m";
+const DIM = "\x1B[2m";
+/**
+* Get the symbol and color for a requirement state.
+*/
+function getSymbolAndColor(state, useColor) {
+	const identity = (s) => s;
+	switch (state) {
+		case "fixed":
+		case "new": return {
+			symbol: "+",
+			colorFn: useColor ? (s) => `${GREEN}${s}${RESET}` : identity
+		};
+		case "regressed":
+		case "absent": return {
+			symbol: "-",
+			colorFn: useColor ? (s) => `${RED}${s}${RESET}` : identity
+		};
+		case "updated": return {
+			symbol: "~",
+			colorFn: useColor ? (s) => `${YELLOW}${s}${RESET}` : identity
+		};
+		default: return {
+			symbol: " ",
+			colorFn: useColor ? (s) => `${DIM}${s}${RESET}` : identity
+		};
+	}
+}
+/**
+* Format the status transition for a requirement.
+*/
+function formatStatusTransition(req) {
+	if (req.state === "new") return "(new)";
+	if (req.state === "absent") return "(absent)";
+	const parts = [];
+	if (req.oldEffectiveStatus && req.newEffectiveStatus) parts.push(`${req.oldEffectiveStatus} → ${req.newEffectiveStatus}`);
+	if (req.state !== "unchanged") parts.push(`(${req.state})`);
+	return parts.join("   ");
+}
+/**
+* Format field changes for full detail.
+*/
+function formatFieldChangesForTerminal(req) {
+	if (req.fieldChanges.length === 0) return "";
+	return req.fieldChanges.map((fc) => {
+		if (fc.op === "add") return `+${fc.path}: ${JSON.stringify(fc.newValue)}`;
+		if (fc.op === "remove") return `-${fc.path}: ${JSON.stringify(fc.oldValue)}`;
+		return `${fc.path}: ${JSON.stringify(fc.oldValue)} → ${JSON.stringify(fc.newValue)}`;
+	}).join("; ");
+}
+/**
+* Render a single requirement line.
+*/
+function renderRequirementLine(req, detail, useColor) {
+	const { symbol, colorFn } = getSymbolAndColor(req.state, useColor);
+	const title = req.title ?? "";
+	const transition = formatStatusTransition(req);
+	let line = `  ${symbol} ${req.id}  ${title}    ${transition}`;
+	if (detail === "full") {
+		if (req.changeReasons.length > 0) line += `  [${req.changeReasons.join(", ")}]`;
+		const fieldChanges = formatFieldChangesForTerminal(req);
+		if (fieldChanges) line += `  ${fieldChanges}`;
+	}
+	return colorFn(line);
+}
+/**
+* Build the summary line.
+*/
+function buildSummaryLine(comparison, useColor) {
+	const { summary } = comparison;
+	const line = `Summary: ${[
+		`${summary.fixed} fixed`,
+		`${summary.regressed} regressed`,
+		`${summary.new} new`,
+		`${summary.absent} absent`,
+		`${summary.unchanged} unchanged`,
+		`${summary.updated} updated`,
+		`(${summary.total} total)`
+	].join(", ")}`;
+	if (useColor) return `${BOLD}${line}${RESET}`;
+	return line;
+}
+/**
+* Build the header line.
+*/
+function buildHeaderLine(comparison, useColor) {
+	const mode = comparison.comparisonMode;
+	const oldSource = comparison.sources.find((s) => s.role === "old" || s.role === "golden" || s.role === "reference");
+	const newSource = comparison.sources.find((s) => s.role === "new" || s.role === "system");
+	let header = `HDF Comparison: ${mode}`;
+	const oldTimestamp = oldSource?.assessmentTimestamp;
+	const newTimestamp = newSource?.assessmentTimestamp;
+	if (oldTimestamp && newTimestamp) {
+		const oldDate = oldTimestamp.split("T")[0];
+		const newDate = newTimestamp.split("T")[0];
+		header += ` (${oldDate} → ${newDate})`;
+	}
+	if (useColor) return `${BOLD}${header}${RESET}`;
+	return header;
+}
+/**
+* Render an HdfComparison for terminal display with optional ANSI colors.
+*
+* - `detail: 'summary'` -- just the summary line
+* - `detail: 'control'` -- requirement list + summary (excludes unchanged)
+* - `detail: 'full'`    -- all requirements including unchanged, with changeReasons and fieldChanges
+*
+* When `color: false`, no ANSI escape codes are emitted.
+* Default detail level: `'control'`. Default color: `true`.
+*/
+function renderTerminal(comparison, options) {
+	const detail = options?.detail ?? "control";
+	const useColor = options?.color ?? true;
+	const lines = [];
+	lines.push(buildHeaderLine(comparison, useColor));
+	lines.push("");
+	if (detail === "summary") {
+		lines.push(buildSummaryLine(comparison, useColor));
+		return lines.join("\n");
+	}
+	const filtered = filterRequirements(comparison.requirementDiffs, options);
+	for (const req of filtered) {
+		if (detail === "control" && req.state === "unchanged") continue;
+		lines.push(renderRequirementLine(req, detail, useColor));
+	}
+	lines.push("");
+	lines.push(buildSummaryLine(comparison, useColor));
+	return lines.join("\n");
+}
+//#endregion
+//#region src/renderers/csv.ts
+/**
+* Escape a value for CSV output.
+*
+* Per RFC 4180:
+* - Fields containing commas, double quotes, or newlines are enclosed in double quotes.
+* - Double quotes within a field are escaped by doubling them.
+*/
+function escapeCsvField(value) {
+	if (value.includes(",") || value.includes("\"") || value.includes("\n") || value.includes("\r")) return `"${value.replace(/"/g, "\"\"")}"`;
+	return value;
+}
+/**
+* Format field changes as a human-readable string.
+*/
+function formatFieldChanges(req) {
+	if (req.fieldChanges.length === 0) return "";
+	return req.fieldChanges.map((fc) => {
+		if (fc.op === "add") return `+${fc.path}: ${JSON.stringify(fc.newValue)}`;
+		if (fc.op === "remove") return `-${fc.path}: ${JSON.stringify(fc.oldValue)}`;
+		return `${fc.path}: ${JSON.stringify(fc.oldValue)} -> ${JSON.stringify(fc.newValue)}`;
+	}).join("; ");
+}
+/**
+* Render an HdfComparison as a CSV string.
+*
+* One row per requirement. Columns:
+* - ID, Title, State, Old Status, New Status, Impact (Old), Impact (New), Change Reasons
+*
+* When `detail: 'full'`, an additional Field Changes column is included.
+*
+* Header row is always included. Standard CSV escaping (RFC 4180).
+* Default detail level: `'control'`.
+*/
+function renderCsv(comparison, options) {
+	const detail = options?.detail ?? "control";
+	const filtered = filterRequirements(comparison.requirementDiffs, options);
+	const headers = [
+		"ID",
+		"Title",
+		"State",
+		"Old Status",
+		"New Status",
+		"Impact (Old)",
+		"Impact (New)",
+		"Change Reasons"
+	];
+	if (detail === "full") headers.push("Field Changes");
+	const lines = [headers.join(",")];
+	for (const req of filtered) {
+		const row = [
+			escapeCsvField(req.id),
+			escapeCsvField(req.title ?? ""),
+			escapeCsvField(req.state),
+			escapeCsvField(req.oldEffectiveStatus ?? ""),
+			escapeCsvField(req.newEffectiveStatus ?? ""),
+			escapeCsvField(req.oldImpact !== void 0 ? String(req.oldImpact) : ""),
+			escapeCsvField(req.newImpact !== void 0 ? String(req.newImpact) : ""),
+			escapeCsvField(req.changeReasons.join(", "))
+		];
+		if (detail === "full") row.push(escapeCsvField(formatFieldChanges(req)));
+		lines.push(row.join(","));
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/renderers/index.ts
+/**
+* Convenience function to render a comparison in any supported format.
+*
+* @param comparison - The HdfComparison document to render
+* @param format - Output format: 'json', 'markdown', 'terminal', or 'csv'
+* @param options - Rendering options (detail level, filters, color)
+* @returns The rendered string
+*/
+function render(comparison, format, options) {
+	switch (format) {
+		case "json": return renderJson(comparison, options);
+		case "markdown": return renderMarkdown(comparison, options);
+		case "terminal": return renderTerminal(comparison, options);
+		case "csv": return renderCsv(comparison, options);
+	}
+}
+//#endregion
+export { EXIT_DETAILED_BASELINE_CHANGED, EXIT_DETAILED_DRIFT_ONLY, EXIT_DETAILED_ERROR, EXIT_DETAILED_FIXES_ONLY, EXIT_DETAILED_IDENTICAL, EXIT_DETAILED_MIXED, EXIT_DETAILED_REGRESSIONS_ONLY, EXIT_DIFFERENCES, EXIT_ERROR, EXIT_IDENTICAL, classifyChangeReasons, classifyDiffStatus, computeDetailedExitCode, computeEffectiveStatus, computeExitCode, computeSummary, createCciMatchStrategy, createExactIdStrategy, createFuzzyTitleStrategy, createMappedIdStrategy, diffBaselines, diffHdf, diffSboms, diffSystems, isV1Format, jaccardSimilarity, matchRequirements, normalizeToV2, render, renderCsv, renderJson, renderMarkdown, renderTerminal, tokenize, validateComparison };
+
 //# sourceMappingURL=index.js.map