open-index/open-npm huggingface dataset:
npm package: @mitre/hdf-diff
Description: Structured comparison of HDF evaluation results — tracks what changed, why, and by how much
Author: MITRE Corporation
Latest version: 2.0.0

# @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
npm package: @mitre/hdf-generators
Description: Generate InSpec profile stubs from HDF Baseline definitions
Author: MITRE Corporation
Latest version: 2.0.0

# @mitre/hdf-generators

Generate InSpec profile stubs from HDF Baseline definitions.

## What it does

Takes an HDF Baseline JSON document (requirement definitions with metadata, descriptions, and tags) and generates a complete InSpec profile directory structure:

- `inspec.yml` — profile metadata (name, maintainer, license, version, platform supports)
- `controls/*.rb` — one control file per requirement with `describe` blocks, tags, and impact

This bridges from HDF's tool-agnostic baseline format to InSpec's executable compliance-as-code format.

## Relationship to other packages

| Package | Relationship |
|---------|-------------|
| **hdf-schema** | Provides the `HDFBaseline` type that generators consume |
| **hdf-converters** | Converters produce baselines (e.g., XCCDF benchmark → HDF baseline) that generators can then turn into InSpec profiles |
| **hdf-cli** | `hdf generate inspec-profile` command wraps this library |
| **hdf-mappings** | Baselines may contain NIST/CCI tags from hdf-mappings |

## Installation

```bash
npm install @mitre/hdf-generators
```

## Usage (TypeScript)

```typescript
import { generateInSpecProfile } from '@mitre/hdf-generators';
import type { HDFBaseline } from '@mitre/hdf-schema';

const baseline: HDFBaseline = JSON.parse(fs.readFileSync('baseline.json', 'utf8'));

const profile = generateInSpecProfile(baseline, {
  maintainer: 'MITRE SAF',
  copyright: 'MITRE Corporation',
  license: 'Apache-2.0',
});

// profile.inspecYml — string content for inspec.yml
// profile.controls  — Map<string, string> of filename → Ruby control code
```

### Individual stubs

```typescript
import { generateControlStub, generateInSpecYml, escapeQuotes } from '@mitre/hdf-generators';

// Generate a single control file
const ruby = generateControlStub(requirement);

// Generate inspec.yml
const yml = generateInSpecYml(baseline, { maintainer: 'Team', license: 'Apache-2.0' });
```

## Usage (Go)

```go
import generators "github.com/mitre/hdf-generators"

profile := generators.GenerateInSpecProfile(baseline, generators.ProfileMetadata{
    Maintainer: "MITRE SAF",
    License:    "Apache-2.0",
})
// profile.InspecYml — string
// profile.Controls  — map[string]string
```

## CLI usage

```bash
hdf generate inspec-profile baseline.json output-dir/
hdf generate inspec-profile baseline.json output-dir/ --maintainer "MITRE SAF"
hdf generate inspec-profile baseline.json output-dir/ --single-file
```

## License

Apache-2.0 © MITRE Corporation