@mitre/hdf-diff 3.0.1 → 3.1.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

@@ -1,26 +1,30 @@
 # @mitre/hdf-diff
 
-Structured comparison of HDF evaluation results — tracks what changed, why, and by how much.
+Structured comparison of HDF documents — 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
+Compares HDF documents (results, baselines, or system documents) and produces a structured diff:
 
-Output formats: JSON, Markdown, CSV, terminal (ANSI-colored).
+- **Results comparison** (`diffHdf`) — requirements added, removed, or changed between evaluations; status transitions with change reasons; field-level changes (impact, severity, disposition, effectiveImpact); per-baseline compliance summaries
+- **Baseline evolution** (`diffBaselines`) — track how a baseline's requirements change across versions (IDs added/removed, impact/severity/title changes)
+- **System drift** (`diffSystems`) — compare two HDF system documents for component, data flow, and configuration changes
+- **SBOM comparison** (`diffSboms`) — CycloneDX/SPDX package-level diffs (added, removed, updated)
+- **Amendment operations** (Go only, `amend` subpackage) — merge overrides into results, verify amendment chains, compute effectiveStatus/effectiveImpact/disposition
+
+Additional capabilities:
+- Multiple comparison modes: temporal, baseline, fleet, multi-source
+- Format normalization: legacy InSpec exec-json (v1) to current HDF
+- Output formats: JSON, Markdown, CSV, terminal (ANSI-colored)
+- CI exit codes: GNU diff-compatible (0/1/2) and detailed (10-14)
 
 ## Relationship to other packages
 
 | Package | Relationship |
 |---------|-------------|
-| **hdf-schema** | Provides the `HDFResults` types that hdf-diff consumes |
+| **hdf-schema** | Provides `HDFResults`, `HDFBaseline`, and system 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 |
+| **hdf-cli** | `hdf diff` and `hdf amend` commands wrap this library for CLI use |
 
 ## Installation
 
@@ -31,16 +35,20 @@ npm install @mitre/hdf-diff
 ## Usage
 
 ```typescript
-import { diffHdf, render } from '@mitre/hdf-diff';
+import { diffHdf, diffBaselines, diffSystems, render } from '@mitre/hdf-diff';
 
-// Compare two evaluation results
+// Compare two evaluation results (temporal mode)
 const comparison = diffHdf(oldResults, newResults);
 
-// Render as markdown
-const md = render(comparison, { format: 'markdown', detail: 'full' });
+// Compare baseline evolution (track requirement changes across versions)
+const baselineDiff = diffBaselines(oldBaseline, newBaseline);
+
+// Compare system documents (component/data-flow drift)
+const systemDiff = diffSystems(oldSystem, newSystem);
 
-// Render as JSON
-const json = render(comparison, { format: 'json' });
+// Render as markdown, JSON, CSV, or terminal
+const md = render(comparison, 'markdown', { detail: 'full' });
+const json = render(comparison, 'json');
 
 // Check exit codes for CI
 import { computeExitCode, EXIT_IDENTICAL } from '@mitre/hdf-diff';
@@ -76,12 +84,36 @@ const sbomDiff = diffSboms(oldSbom, newSbom);
 ## CLI usage
 
 ```bash
+# Results comparison
 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
+
+# System drift detection
+hdf diff old-system.json new-system.json
+
+# SBOM comparison
 hdf diff --sbom old-sbom.json new-sbom.json
+
+# Baseline mode (golden baseline vs current scan)
+hdf diff --mode baseline golden.json current.json
+```
+
+## Go usage
+
+The diff engine is also available as a Go module:
+
+```go
+import diff "github.com/mitre/hdf-libs/hdf-diff/go"
 ```
 
+See the [hdf-diff/go](https://github.com/mitre/hdf-libs/tree/main/hdf-diff/go) directory for the Go API.
+
+## Schema documentation
+
+The HDF Comparison schema that hdf-diff produces is documented at
+<https://mitre.github.io/hdf-libs/schemas/>.
+
 ## License
 
 Apache-2.0 © MITRE Corporation