@mitre/hdf-diff 2.0.0

package/LICENSE.md

@@ -0,0 +1,55 @@
+# License
+
+Copyright © 2025 The MITRE Corporation.
+
+Approved for Public Release; Distribution Unlimited. Case Number 18-3678.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain a
+copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+
+## Redistribution Terms
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright/digital
+  rights legend, this list of conditions and the following Notice.
+- Redistributions in binary form must reproduce the above
+  copyright/digital rights legend, this list of conditions and the
+  following Notice in the documentation and/or other materials provided
+  with the distribution.
+- Neither the name of The MITRE Corporation nor the names of its contributors
+  may be used to endorse or promote products derived from this software
+  without specific prior written permission.
+
+## Notice
+
+The MITRE Corporation grants permission to reproduce, distribute, modify, and
+otherwise use this software to the extent permitted by the licensed terms
+provided in the LICENSE file included with this project.
+
+This software was produced by The MITRE Corporation for the U.S. Government
+under contract. As such the U.S. Government has certain use and data
+rights in this software. No use other than those granted to the U.S.
+Government, or to those acting on behalf of the U.S. Government, under
+these contract arrangements is authorized without the express written
+permission of The MITRE Corporation.
+
+Some files in this codebase were generated by generative AI, under the
+direction and review of The MITRE Corporation employees, for the purpose of
+development efficiency. All AI-generated code functionality was validated
+by standard quality and assurance testing.
+
+For further information, please contact The MITRE Corporation,
+Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539,
+(703) 983-6000.

package/README.md

@@ -0,0 +1,87 @@
+# @mitre/hdf-diff
+
+Structured comparison of HDF evaluation results — tracks what changed, why, and by how much.
+
+## What it does
+
+Compares two HDF results documents and produces a structured diff showing:
+- Requirements added, removed, or changed between evaluations
+- Status transitions (passed→failed, failed→passed, etc.) with change reasons
+- Field-level changes (impact, title, severity)
+- Per-baseline and per-component compliance summaries
+- SBOM (CycloneDX/SPDX) package-level diffs
+
+Output formats: JSON, Markdown, CSV, terminal (ANSI-colored).
+
+## Relationship to other packages
+
+| Package | Relationship |
+|---------|-------------|
+| **hdf-schema** | Provides the `HDFResults` types that hdf-diff consumes |
+| **hdf-validators** | Used to validate comparison output against the HDF comparison schema |
+| **hdf-cli** | `hdf diff` command wraps this library for CLI use |
+| **hdf-parsers** | Not used — hdf-diff operates on typed structs, not raw JSON |
+
+## Installation
+
+```bash
+npm install @mitre/hdf-diff
+```
+
+## Usage
+
+```typescript
+import { diffHdf, render } from '@mitre/hdf-diff';
+
+// Compare two evaluation results
+const comparison = diffHdf(oldResults, newResults);
+
+// Render as markdown
+const md = render(comparison, { format: 'markdown', detail: 'full' });
+
+// Render as JSON
+const json = render(comparison, { format: 'json' });
+
+// Check exit codes for CI
+import { computeExitCode, EXIT_IDENTICAL } from '@mitre/hdf-diff';
+const code = computeExitCode(comparison);
+if (code !== EXIT_IDENTICAL) process.exit(code);
+```
+
+### Requirement matching
+
+hdf-diff supports multiple strategies for matching requirements across evaluations:
+- **Exact ID** (default) — match by requirement ID
+- **Mapped ID** — match via a user-provided ID mapping
+- **CCI match** — match by shared CCI identifiers
+- **Fuzzy title** — Jaccard similarity on tokenized titles
+
+```typescript
+import { diffHdf, createFuzzyTitleStrategy } from '@mitre/hdf-diff';
+
+const comparison = diffHdf(oldResults, newResults, {
+  matchStrategy: createFuzzyTitleStrategy(0.8), // 80% similarity threshold
+});
+```
+
+### SBOM comparison
+
+```typescript
+import { diffSboms } from '@mitre/hdf-diff';
+
+const sbomDiff = diffSboms(oldSbom, newSbom);
+// Shows packages added, removed, updated, or unchanged
+```
+
+## CLI usage
+
+```bash
+hdf diff old-results.json new-results.json
+hdf diff old-results.json new-results.json --format markdown
+hdf diff old-results.json new-results.json --json
+hdf diff --sbom old-sbom.json new-sbom.json
+```
+
+## License
+
+Apache-2.0 © MITRE Corporation

package/dist/diff.d.ts

@@ -0,0 +1,49 @@
+import type { HdfComparison } from './types.js';
+/**
+ * Options for configuring the diff behavior.
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function diffSystems(oldSystem: Record<string, unknown>, newSystem: Record<string, unknown>, options?: DiffOptions): HdfComparison;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAMd,MAAM,YAAY,CAAC;AAUpB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,aAAa,GAAG,mBAAmB,GAAG,aAAa,CAAC;IACzG,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/D,OAAO,CAAC,EAAE,WAAW,GACpB,aAAa,CA8Ff;AA4WD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,WAAW,GACpB,aAAa,CA2If;AAsBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,OAAO,CAAC,EAAE,WAAW,GACpB,aAAa,CA6Ff"}