JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 447
  • Score
    100M100P100Q93907F
  • License Apache-2.0

Structured comparison of HDF evaluation results — tracks what changed, why, and by how much

Package Exports

  • @mitre/hdf-diff

Readme

@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

npm install @mitre/hdf-diff

Usage

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
import { diffHdf, createFuzzyTitleStrategy } from '@mitre/hdf-diff';

const comparison = diffHdf(oldResults, newResults, {
  matchStrategy: createFuzzyTitleStrategy(0.8), // 80% similarity threshold
});

SBOM comparison

import { diffSboms } from '@mitre/hdf-diff';

const sbomDiff = diffSboms(oldSbom, newSbom);
// Shows packages added, removed, updated, or unchanged

CLI usage

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