@mitre/hdf-diff 3.5.0 → 3.6.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -66,10 +66,11 @@ hdf-diff supports multiple strategies for matching requirements across evaluatio
66
66
  - **Fuzzy title** — Jaccard similarity on tokenized titles
67
67
 
68
68
  ```typescript
69
- import { diffHdf, createFuzzyTitleStrategy } from '@mitre/hdf-diff';
69
+ import { diffHdf } from '@mitre/hdf-diff';
70
70
 
71
71
  const comparison = diffHdf(oldResults, newResults, {
72
- matchStrategy: createFuzzyTitleStrategy(0.8), // 80% similarity threshold
72
+ matchStrategy: 'fuzzyTitle',
73
+ minConfidence: 0.8, // 80% similarity threshold
73
74
  });
74
75
  ```
75
76
 
@@ -96,7 +97,7 @@ hdf diff old-system.json new-system.json
96
97
  # SBOM comparison
97
98
  hdf diff --sbom old.cdx.json new.cdx.json
98
99
 
99
- # Encode the security outcome in the exit code (10=fixes, 11=regressions, 12=mixed, 13=baseline change)
100
+ # Encode the security outcome in the exit code (10=fixes, 11=regressions, 12=mixed, 13=baseline change, 14=metadata drift only)
100
101
  hdf diff old-results.json new-results.json --detailed-exitcode
101
102
  ```
102
103
 
package/dist/index.d.ts CHANGED
@@ -325,11 +325,12 @@ declare function diffSystems(oldSystem: Record<string, unknown>, newSystem: Reco
325
325
  * overrides, delegating to the canonical shared implementation in
326
326
  * `@mitre/hdf-utilities` (see status-determination.md):
327
327
  *
328
- * 1. impact === 0 → notApplicable (regardless of results)
329
- * 2. the governing (most recent non-expired) status override's status
330
- * 3. effectiveStatus field set (and no statusOverrides) → use it
331
- * 4. Aggregate results using worst-wins
332
- * 5. Empty results → notReviewed
328
+ * 1. the governing (most recent non-expired) status override's status
329
+ * 2. else result roll-up error → error
330
+ * 3. else impact === 0 → notApplicable
331
+ * 4. else worst-wins roll-up of the results (empty → notReviewed)
332
+ *
333
+ * The stored effectiveStatus field is an output cache and is never read.
333
334
  */
334
335
  declare function computeEffectiveStatus(requirement: Record<string, unknown>, referenceTimestamp?: string): string;
335
336
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/sbom.ts","../src/types.ts","../src/diff.ts","../src/status.ts","../src/effective-checksum.ts","../src/change-event.ts","../src/apply-events.ts","../src/fold-events.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/srg-deterministic.ts","../src/matching/srg-cci-tiebreak.ts","../src/matching/vendor-fuzzy-title.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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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/sbom.ts","../src/types.ts","../src/diff.ts","../src/status.ts","../src/effective-checksum.ts","../src/change-event.ts","../src/apply-events.ts","../src/fold-events.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/srg-deterministic.ts","../src/matching/srg-cci-tiebreak.ts","../src/matching/vendor-fuzzy-title.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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"}
package/dist/index.js CHANGED
@@ -14,18 +14,18 @@ const FAILING_STATUSES = /* @__PURE__ */ new Set([
14
14
  * overrides, delegating to the canonical shared implementation in
15
15
  * `@mitre/hdf-utilities` (see status-determination.md):
16
16
  *
17
- * 1. impact === 0 → notApplicable (regardless of results)
18
- * 2. the governing (most recent non-expired) status override's status
19
- * 3. effectiveStatus field set (and no statusOverrides) → use it
20
- * 4. Aggregate results using worst-wins
21
- * 5. Empty results → notReviewed
17
+ * 1. the governing (most recent non-expired) status override's status
18
+ * 2. else result roll-up error → error
19
+ * 3. else impact === 0 → notApplicable
20
+ * 4. else worst-wins roll-up of the results (empty → notReviewed)
21
+ *
22
+ * The stored effectiveStatus field is an output cache and is never read.
22
23
  */
23
24
  function computeEffectiveStatus(requirement, referenceTimestamp) {
24
25
  const results = requirement["results"] ?? [];
25
26
  const overrides = requirement["statusOverrides"] ?? [];
26
27
  return computeEffectiveStatus$1({
27
28
  impact: requirement["impact"] ?? NaN,
28
- effectiveStatus: requirement["effectiveStatus"],
29
29
  resultStatuses: results.map((r) => r.status),
30
30
  overrides: overrides.map((o) => ({
31
31
  status: o.status,
@@ -139,6 +139,15 @@ function computeSummary(requirements) {
139
139
  //#endregion
140
140
  //#region src/normalize.ts
141
141
  /**
142
+ * Normalize InSpec exec-json v1 format to HDF v2 structure for diffing.
143
+ *
144
+ * V1 uses: profiles[].controls[].results[].code_desc, source_location, start_time
145
+ * V2 uses: baselines[].requirements[].results[].codeDesc, sourceLocation, startTime
146
+ *
147
+ * This module detects v1 documents and converts them in-memory to v2 shape
148
+ * so the diff engine only needs to handle one format.
149
+ */
150
+ /**
142
151
  * Detect whether a document is v1 (InSpec exec-json) format.
143
152
  * V1 has `profiles` at the top level; v2 has `baselines`.
144
153
  */
@@ -215,8 +224,8 @@ function normalizeResultStatus(v1Status) {
215
224
  */
216
225
  function normalizeTimestamp(timestamp) {
217
226
  if (timestamp.includes("T")) return timestamp;
218
- const parsed = new Date(timestamp);
219
- if (!isNaN(parsed.getTime())) return parsed.toISOString();
227
+ const parsed = parseTimestamp(timestamp);
228
+ if (parsed) return parsed.toISOString();
220
229
  return timestamp;
221
230
  }
222
231
  function normalizeResult(result) {
@@ -1195,6 +1204,13 @@ const DEFAULT_TRACKED_FIELDS = [
1195
1204
  "tags"
1196
1205
  ];
1197
1206
  /**
1207
+ * Round a fuzzy-match confidence (0-1 similarity) to 4 decimal places to strip
1208
+ * IEEE-754 noise from the serialized matchConfidence value.
1209
+ */
1210
+ function roundConfidence(x) {
1211
+ return Math.round(x * 1e4) / 1e4;
1212
+ }
1213
+ /**
1198
1214
  * Extract a dataSource label from a document, if available.
1199
1215
  * Looks for `dataSource.name` in the raw (pre-normalized) document.
1200
1216
  */
@@ -1441,7 +1457,7 @@ function comparePair(oldNormalized, newNormalized, oldTimestamp, newTimestamp, t
1441
1457
  before: oldReq,
1442
1458
  after: newReq,
1443
1459
  matchStrategy: pair.strategy,
1444
- matchConfidence: pair.confidence
1460
+ matchConfidence: roundConfidence(pair.confidence)
1445
1461
  });
1446
1462
  }
1447
1463
  for (const req of matchResult.unmatchedOld) {
@@ -1936,7 +1952,7 @@ function diffBaselines(oldBaseline, newBaseline, options) {
1936
1952
  before: oldReq,
1937
1953
  after: newReq,
1938
1954
  matchStrategy: pair.strategy,
1939
- matchConfidence: pair.confidence
1955
+ matchConfidence: roundConfidence(pair.confidence)
1940
1956
  });
1941
1957
  }
1942
1958
  for (const req of matchResult.unmatchedOld) {
@@ -2464,7 +2480,7 @@ async function verifyEventChain(chain, seedReq, inSeed, keyWarn) {
2464
2480
  if (ev["state"] === "new") {
2465
2481
  if (inSeed) keyWarn("newOnExisting", "state new for a key already present in the seed");
2466
2482
  else if (prior !== "") keyWarn("chainGap", "new-state event carries a non-null priorChecksum");
2467
- } else if (prior !== expected) keyWarn("chainGap", `priorChecksum "${prior}" does not match expected chain state "${expected}"`);
2483
+ } else if (prior !== expected) keyWarn("chainGap", `priorChecksum "${prior}" does not match expected chain state "${expected}" — either events are missing from this chain, or it was derived under an older effective-status semantics (see status-determination.md); re-derive from a fresh rescan to re-anchor`);
2468
2484
  expected = await requirementChecksum(ev["after"], ev["timestamp"]);
2469
2485
  }
2470
2486
  }