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

package/dist/index.d.ts

@@ -1,17 +1,623 @@
-export type { ChangeReason, RequirementState, FieldChange, RequirementDiff, ComponentDiff, ComparisonSummary, BaselineDiff, Source, Annotation, MatchingConfig, HdfComparison, } from './types.js';
-export type { DiffStatus, DiffSummary, HdfDiff, } from './types.js';
-export { diffHdf, diffBaselines, diffSystems } from './diff.js';
-export type { DiffOptions } from './diff.js';
-export { computeEffectiveStatus, classifyChangeReasons, classifyDiffStatus, } from './status.js';
-export { computeSummary } from './summary.js';
-export { isV1Format, normalizeToV2 } from './normalize.js';
-export { matchRequirements, createExactIdStrategy, createMappedIdStrategy, createCciMatchStrategy, createFuzzyTitleStrategy, tokenize, jaccardSimilarity, } from './matching/index.js';
-export type { MatchResult, MatchPair, MatchStrategy, MatchOptions, } from './matching/index.js';
-export { validateComparison } from './validate.js';
-export type { ValidationResult } from './validate.js';
-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';
-export { render, renderJson, renderMarkdown, renderTerminal, renderCsv } from './renderers/index.js';
-export type { DetailLevel, RenderOptions } from './renderers/types.js';
-export { diffSboms } from './sbom.js';
-export type { PackageDiff, SbomDiffResult } from './sbom.js';
+//#region src/sbom.d.ts
+/**
+ * SBOM comparison for the HDF diff engine.
+ *
+ * Compares two SBOM documents (CycloneDX or SPDX JSON) and produces
+ * package-level diffs: added, removed, updated, unchanged packages.
+ *
+ * Format auto-detection:
+ * - CycloneDX: has `bomFormat: "CycloneDX"`, packages in `components[]`
+ * - SPDX: has `spdxVersion`, packages in `packages[]`
+ */
+/**
+ * The comparison result for a single package between two SBOMs.
+ */
+interface PackageDiff {
+  purl: string;
+  name: string;
+  state: 'added' | 'removed' | 'updated' | 'unchanged';
+  oldVersion?: string;
+  newVersion?: string;
+  licenses?: string[];
+}
+/**
+ * The complete result of comparing two SBOM documents.
+ */
+interface SbomDiffResult {
+  packageDiffs: PackageDiff[];
+  added: number;
+  removed: number;
+  updated: number;
+  unchanged: number;
+}
+/**
+ * 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
+ */
+declare function diffSboms(oldJson: string, newJson: string): SbomDiffResult;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Why a requirement's effective status changed between two evaluations.
+ *
+ * Aligned with the hdf-comparison schema's Change_Reason enum:
+ * - resultChanged: The underlying test results differ (e.g., a fix was deployed)
+ * - overrideAdded: A new statusOverride (waiver/attestation) was added
+ * - overrideExpired: A statusOverride present in the old scan has expired by the new scan's timestamp
+ * - overrideRemoved: A statusOverride was removed between scans
+ * - overrideModified: An existing statusOverride was modified (reserved for future use)
+ * - impactChanged: The impact score changed (e.g., from 0.7 to 0.0 means N/A)
+ * - baselineUpgraded: The baseline version changed (reserved for future use)
+ * - controlMapped: A control was mapped to a different framework (reserved for future use)
+ * - scannerChanged: A different scanner was used (reserved for future use)
+ * - targetChanged: The scan target changed (reserved for future use)
+ * - configChanged: The scan configuration changed (reserved for future use)
+ * - metadataChanged: Non-impact baseline metadata changed (tags, descriptions, title, etc.)
+ */
+type ChangeReason = 'resultChanged' | 'overrideAdded' | 'overrideExpired' | 'overrideRemoved' | 'overrideModified' | 'impactChanged' | 'baselineUpgraded' | 'controlMapped' | 'scannerChanged' | 'targetChanged' | 'configChanged' | 'metadataChanged' | 'dispositionChanged' | 'effectiveImpactChanged';
+/**
+ * Classification of how a requirement's state changed between evaluations.
+ * Uses SARIF-inspired vocabulary.
+ *
+ * - new: Requirement exists only in the new evaluation (was "added")
+ * - absent: Requirement exists only in the old evaluation (was "removed")
+ * - unchanged: Same effective status in both evaluations
+ * - updated: Status changed but doesn't fit fixed/regressed (was "changed")
+ * - fixed: Was failing/error, now passing
+ * - regressed: Was passing, now failing/error
+ * - moved: Requirement ID changed but content is the same (future use)
+ * - split: One requirement became multiple (future use)
+ * - merged: Multiple requirements became one (future use)
+ */
+type RequirementState = 'new' | 'absent' | 'unchanged' | 'updated' | 'fixed' | 'regressed' | 'moved' | 'split' | 'merged';
+/**
+ * A field-level difference on a requirement, following JSON Patch-like conventions.
+ */
+interface FieldChange {
+  /** The operation type: add, remove, or replace */
+  op: 'add' | 'remove' | 'replace';
+  /** Dot-notation path to the changed field (e.g., 'impact', 'tags.cci') */
+  path: string;
+  /** Value in the old evaluation (undefined for 'add' operations) */
+  oldValue?: unknown;
+  /** Value in the new evaluation (undefined for 'remove' operations) */
+  newValue?: unknown;
+}
+/**
+ * The diff for a single requirement across two evaluations.
+ */
+interface RequirementDiff {
+  /** The requirement ID (e.g., 'SV-238196') */
+  id: string;
+  /** Classification of the change */
+  state: RequirementState;
+  /** Why the status changed — empty array if unchanged */
+  changeReasons: ChangeReason[];
+  /** Full snapshot of the requirement from the old evaluation (null when state = 'new') */
+  before: Record<string, unknown> | null;
+  /** Full snapshot of the requirement from the new evaluation (null when state = 'absent') */
+  after: Record<string, unknown> | null;
+  /** The requirement title (from whichever evaluation has it) */
+  title?: string;
+  /** Effective status in the old evaluation (undefined if new) */
+  oldEffectiveStatus?: string;
+  /** Effective status in the new evaluation (undefined if absent) */
+  newEffectiveStatus?: string;
+  /** Impact in the old evaluation */
+  oldImpact?: number;
+  /** Impact in the new evaluation */
+  newImpact?: number;
+  /** Field-level diffs for non-status fields */
+  fieldChanges: FieldChange[];
+  /** The matching strategy that paired this requirement (e.g., 'exactId') */
+  matchStrategy?: string;
+  /** Confidence of the match (0.0-1.0) */
+  matchConfidence?: number;
+  /** Index into the sources array for fleet mode */
+  sourceIndex?: number;
+}
+/**
+ * Summary counts for the comparison.
+ */
+interface ComparisonSummary {
+  /** Requirements that went from failing/error to passing */
+  fixed: number;
+  /** Requirements that went from passing to failing/error */
+  regressed: number;
+  /** Requirements present only in the new evaluation (was "added") */
+  new: number;
+  /** Requirements present only in the old evaluation (was "removed") */
+  absent: number;
+  /** Requirements with the same effective status */
+  unchanged: number;
+  /** Requirements whose status changed in a way other than fixed/regressed (was "changed") */
+  updated: number;
+  /** Total unique requirements across both evaluations */
+  total: number;
+  /** Number of requirements matched between old and new */
+  matchedCount: number;
+  /** Number of requirements only in old (unmatched) */
+  unmatchedOldCount: number;
+  /** Number of requirements only in new (unmatched) */
+  unmatchedNewCount: number;
+}
+/**
+ * The diff for a single component across two system documents.
+ * Used in systemDrift comparison mode.
+ */
+interface ComponentDiff {
+  /** Component name */
+  name: string;
+  /** Classification of the change: new, absent, unchanged, or updated */
+  state: 'new' | 'absent' | 'unchanged' | 'updated';
+  /** Component snapshot from the old system (null when state = 'new') */
+  before: Record<string, unknown> | null;
+  /** Component snapshot from the new system (null when state = 'absent') */
+  after: Record<string, unknown> | null;
+  /** Field-level diffs between old and new component */
+  fieldChanges: FieldChange[];
+}
+/**
+ * The diff for a single baseline across two evaluations.
+ */
+interface BaselineDiff {
+  /** Baseline name */
+  name: string;
+  /** Version in the old evaluation */
+  oldVersion?: string;
+  /** Version in the new evaluation */
+  newVersion?: string;
+  /** Whether this baseline was new, absent, updated, or unchanged */
+  state: 'new' | 'absent' | 'updated' | 'unchanged';
+}
+/**
+ * Metadata about a source document used in the comparison.
+ */
+interface Source {
+  /** Role of the source in the comparison */
+  role: 'old' | 'new' | 'golden' | 'reference' | 'system';
+  /** Human-readable label */
+  label: string;
+  /** URI to the source document */
+  uri?: string;
+  /** Original format of the source (e.g., 'hdf-results-v2', 'inspec-exec-json-v1') */
+  originalFormat?: string;
+  /** Assessment timestamp from the source document */
+  assessmentTimestamp?: string;
+}
+/**
+ * An annotation attached to a requirement diff.
+ */
+interface Annotation {
+  /** Human-readable label */
+  label: string;
+  /** Description of the annotation */
+  text: string;
+  /** When the annotation was created */
+  timestamp?: string;
+}
+/**
+ * The top-level comparison result comparing two or more HDF evaluations.
+ */
+interface HdfComparison {
+  /** Schema version for the comparison format */
+  formatVersion: '1.0.0';
+  /** The mode of comparison */
+  comparisonMode: 'temporal' | 'baseline' | 'fleet' | 'multiSource' | 'baselineEvolution' | 'systemDrift';
+  /** When the comparison was generated */
+  timestamp?: string;
+  /** Source documents used in the comparison */
+  sources: Source[];
+  /** Matching configuration used */
+  matching?: MatchingConfig;
+  /** Aggregate counts */
+  summary: ComparisonSummary;
+  /** Per-baseline diffs */
+  baselineDiffs: BaselineDiff[];
+  /** Per-requirement diffs, sorted by id */
+  requirementDiffs: RequirementDiff[];
+  /** Per-component diffs (systemDrift mode only) */
+  componentDiffs?: ComponentDiff[];
+  /** Per-package diffs from embedded SBOM comparison (systemDrift mode only) */
+  packageDiffs?: PackageDiff[];
+  /** URI identifying the system being compared (systemDrift mode only) */
+  systemRef?: string;
+  /** Requirements that drifted from a golden baseline (future use) */
+  drift?: RequirementDiff[];
+  /** Annotations keyed by requirement ID */
+  annotations?: Record<string, Annotation>;
+  /** Extension data for custom integrations */
+  extensions?: Record<string, unknown>;
+}
+/**
+ * Configuration for how requirements are matched between evaluations.
+ */
+interface MatchingConfig {
+  /** The primary strategy used for matching requirements across sources */
+  primaryStrategy: string;
+  /** Minimum confidence threshold for a match */
+  confidenceThreshold?: number;
+}
+/** @deprecated Use RequirementState instead */
+type DiffStatus = RequirementState;
+/** @deprecated Use ComparisonSummary instead */
+type DiffSummary = ComparisonSummary;
+/** @deprecated Use HdfComparison instead */
+type HdfDiff = HdfComparison;
+//#endregion
+//#region src/diff.d.ts
+/**
+ * Options for configuring the diff behavior.
+ */
+interface DiffOptions {
+  /** Fields to track for field-level diffs (default: ['impact', 'severity', 'tags']) */
+  trackedFields?: string[];
+  /** Comparison mode (default: 'temporal') */
+  comparisonMode?: 'temporal' | 'baseline' | 'fleet' | 'multiSource' | 'baselineEvolution' | 'systemDrift';
+  /** Primary matching strategy name (default: 'exactId') */
+  matchStrategy?: string;
+  /** Fallback strategy names, applied in order to remaining unmatched requirements */
+  fallbackStrategies?: string[];
+  /** Mapping table for the 'mappedId' strategy (old ID -> new ID) */
+  mappingTable?: Record<string, string>;
+  /** Minimum confidence threshold for fuzzy matching (default: 0.6) */
+  minConfidence?: number;
+  /** Validate output against hdf-comparison schema. Default: false (performance). */
+  validateOutput?: boolean;
+}
+/**
+ * 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).
+ */
+declare function diffHdf(oldResults: Record<string, unknown>, newResults: Record<string, unknown> | Record<string, unknown>[], options?: DiffOptions): HdfComparison;
+/**
+ * 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.
+ */
+declare function diffBaselines(oldBaseline: Record<string, unknown>, newBaseline: Record<string, unknown>, options?: DiffOptions): HdfComparison;
+/**
+ * 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.
+ */
+declare function diffSystems(oldSystem: Record<string, unknown>, newSystem: Record<string, unknown>, options?: DiffOptions): HdfComparison;
+//#endregion
+//#region src/status.d.ts
+/**
+ * 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
+ */
+declare function computeEffectiveStatus(requirement: Record<string, unknown>, referenceTimestamp?: string): string;
+/**
+ * Classify why the status changed between two requirements.
+ * Returns an array of change reasons (a status change can have multiple causes).
+ */
+declare function classifyChangeReasons(oldReq: Record<string, unknown>, newReq: Record<string, unknown>, oldTimestamp?: string, newTimestamp?: string): ChangeReason[];
+/**
+ * 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'
+ */
+declare function classifyDiffStatus(oldEffectiveStatus: string, newEffectiveStatus: string): RequirementState;
+//#endregion
+//#region src/summary.d.ts
+/**
+ * Compute summary counts from an array of RequirementDiff entries.
+ */
+declare function computeSummary(requirements: RequirementDiff[]): ComparisonSummary;
+//#endregion
+//#region src/normalize.d.ts
+/**
+ * Normalize InSpec exec-json v1 format to HDF v2 structure for diffing.
+ *
+ * V1 uses: profiles[].controls[].results[].code_desc, source_location, start_time
+ * V2 uses: baselines[].requirements[].results[].codeDesc, sourceLocation, startTime
+ *
+ * This module detects v1 documents and converts them in-memory to v2 shape
+ * so the diff engine only needs to handle one format.
+ */
+/**
+ * Detect whether a document is v1 (InSpec exec-json) format.
+ * V1 has `profiles` at the top level; v2 has `baselines`.
+ */
+declare function isV1Format(doc: Record<string, unknown>): boolean;
+/**
+ * Normalize a document to v2-like structure. If already v2, returns as-is.
+ * If v1, converts profiles→baselines, controls→requirements, and snake_case→camelCase.
+ */
+declare function normalizeToV2(doc: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+//#region src/matching/types.d.ts
+/**
+ * Result of matching requirements between two evaluations.
+ */
+interface MatchResult {
+  /** Paired requirements with their match metadata */
+  matched: MatchPair[];
+  /** Requirements only in the old evaluation (unmatched) */
+  unmatchedOld: Record<string, unknown>[];
+  /** Requirements only in the new evaluation (unmatched) */
+  unmatchedNew: Record<string, unknown>[];
+}
+/**
+ * A single matched pair of requirements.
+ */
+interface MatchPair {
+  /** The requirement from the old evaluation */
+  oldReq: Record<string, unknown>;
+  /** The requirement from the new evaluation */
+  newReq: Record<string, unknown>;
+  /** Name of the strategy that produced this match */
+  strategy: string;
+  /** Confidence score for the match (0.0 - 1.0) */
+  confidence: number;
+}
+/**
+ * A pluggable strategy for matching requirements between evaluations.
+ */
+interface MatchStrategy {
+  /** Unique name for this strategy */
+  name: string;
+  /** Match old requirements against new requirements */
+  match(oldReqs: Record<string, unknown>[], newReqs: Record<string, unknown>[]): MatchResult;
+}
+//#endregion
+//#region src/matching/exact-id.d.ts
+/**
+ * Create an exact ID matching strategy.
+ *
+ * Matches requirements by their `id` field with exact string equality.
+ * Confidence is always 1.0 for matches.
+ */
+declare function createExactIdStrategy(): MatchStrategy;
+//#endregion
+//#region src/matching/mapped-id.d.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).
+ */
+declare function createMappedIdStrategy(mapping: Record<string, string>): MatchStrategy;
+//#endregion
+//#region src/matching/cci-match.d.ts
+/**
+ * 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.
+ */
+declare function createCciMatchStrategy(): MatchStrategy;
+//#endregion
+//#region src/matching/fuzzy-match.d.ts
+/**
+ * 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
+ */
+declare function tokenize(text: string): Set<string>;
+/**
+ * Compute Jaccard similarity between two sets.
+ * Returns |intersection| / |union|, or 0 if both sets are empty.
+ */
+declare function jaccardSimilarity(a: Set<string>, b: Set<string>): number;
+/**
+ * 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)
+ */
+declare function createFuzzyTitleStrategy(minConfidence?: number): MatchStrategy;
+//#endregion
+//#region src/matching/index.d.ts
+/**
+ * Options for configuring requirement matching.
+ */
+interface MatchOptions {
+  /** Primary matching strategy name (default: 'exactId') */
+  strategy?: string;
+  /** Fallback strategy names, applied in order to remaining unmatched requirements */
+  fallbackStrategies?: string[];
+  /** Mapping table for the 'mappedId' strategy (old ID -> new ID) */
+  mappingTable?: Record<string, string>;
+  /** Minimum confidence threshold for fuzzy matching (default: 0.6) */
+  minConfidence?: number;
+}
+/**
+ * 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
+ */
+declare function matchRequirements(oldReqs: Record<string, unknown>[], newReqs: Record<string, unknown>[], options?: MatchOptions): MatchResult;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Result of validating a document against the hdf-comparison schema.
+ */
+interface ValidationResult {
+  /** Whether the document conforms to the schema */
+  valid: boolean;
+  /** Human-readable error messages (only present when valid is false) */
+  errors?: string[];
+}
+/**
+ * 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
+ */
+declare function validateComparison(doc: unknown): ValidationResult;
+//#endregion
+//#region src/exit-codes.d.ts
+/** GNU diff compatible exit codes (--exit-code mode) */
+declare const EXIT_IDENTICAL = 0;
+declare const EXIT_DIFFERENCES = 1;
+declare const EXIT_ERROR = 2;
+/** Detailed exit codes (--detailed-exitcode mode) */
+declare const EXIT_DETAILED_IDENTICAL = 0;
+declare const EXIT_DETAILED_ERROR = 1;
+declare const EXIT_DETAILED_FIXES_ONLY = 10;
+declare const EXIT_DETAILED_REGRESSIONS_ONLY = 11;
+declare const EXIT_DETAILED_MIXED = 12;
+declare const EXIT_DETAILED_BASELINE_CHANGED = 13;
+declare 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.
+ */
+declare function computeExitCode(summary: ComparisonSummary): number;
+/**
+ * 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)
+ */
+declare function computeDetailedExitCode(summary: ComparisonSummary): number;
+//#endregion
+//#region src/renderers/types.d.ts
+type DetailLevel = 'summary' | 'control' | 'full';
+interface RenderOptions {
+  /** What detail to show. Default: 'control' */
+  detail?: DetailLevel;
+  /** Only show requirements matching these states */
+  filterStates?: string[];
+  /** Only show requirements matching this severity */
+  filterSeverity?: string;
+  /** Use color codes (for terminal). Default: true */
+  color?: boolean;
+}
+//#endregion
+//#region src/renderers/json.d.ts
+/**
+ * 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'`.
+ */
+declare function renderJson(comparison: HdfComparison, options?: RenderOptions): string;
+//#endregion
+//#region src/renderers/markdown.d.ts
+/**
+ * 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'`.
+ */
+declare function renderMarkdown(comparison: HdfComparison, options?: RenderOptions): string;
+//#endregion
+//#region src/renderers/terminal.d.ts
+/**
+ * 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`.
+ */
+declare function renderTerminal(comparison: HdfComparison, options?: RenderOptions): string;
+//#endregion
+//#region src/renderers/csv.d.ts
+/**
+ * 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'`.
+ */
+declare function renderCsv(comparison: HdfComparison, options?: RenderOptions): string;
+//#endregion
+//#region src/renderers/index.d.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
+ */
+declare function render(comparison: HdfComparison, format: 'json' | 'markdown' | 'terminal' | 'csv', options?: RenderOptions): string;
+//#endregion
+export { type Annotation, type BaselineDiff, type ChangeReason, type ComparisonSummary, type ComponentDiff, type DetailLevel, type DiffOptions, type DiffStatus, type DiffSummary, 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, type FieldChange, type HdfComparison, type HdfDiff, type MatchOptions, type MatchPair, type MatchResult, type MatchStrategy, type MatchingConfig, type PackageDiff, type RenderOptions, type RequirementDiff, type RequirementState, type SbomDiffResult, type Source, type ValidationResult, 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.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,MAAM,EACN,UAAU,EACV,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,UAAU,EACV,WAAW,EACX,OAAO,GACR,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAChE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG3D,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,QAAQ,EACR,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,WAAW,EACX,SAAS,EACT,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGtD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,8BAA8B,EAC9B,mBAAmB,EACnB,8BAA8B,EAC9B,wBAAwB,EACxB,eAAe,EACf,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACrG,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGvE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/sbom.ts","../src/types.ts","../src/diff.ts","../src/status.ts","../src/summary.ts","../src/normalize.ts","../src/matching/types.ts","../src/matching/exact-id.ts","../src/matching/mapped-id.ts","../src/matching/cci-match.ts","../src/matching/fuzzy-match.ts","../src/matching/index.ts","../src/validate.ts","../src/exit-codes.ts","../src/renderers/types.ts","../src/renderers/json.ts","../src/renderers/markdown.ts","../src/renderers/terminal.ts","../src/renderers/csv.ts","../src/renderers/index.ts"],"mappings":"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"}