@mitre/hdf-diff 3.4.4 → 3.5.0
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 +1 -0
- package/dist/index.d.ts +156 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +514 -39
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.js
CHANGED
|
@@ -1,14 +1,6 @@
|
|
|
1
|
+
import { computeEffectiveStatus as computeEffectiveStatus$1, formatTimestamp, governingOverrideIndex, parseCvssVector, parseTimestamp, sha256 } from "@mitre/hdf-utilities";
|
|
1
2
|
import { validateComparison as validateComparison$1 } from "@mitre/hdf-validators";
|
|
2
|
-
import { parseCvssVector } from "@mitre/hdf-utilities";
|
|
3
3
|
//#region src/status.ts
|
|
4
|
-
/** Status severity ranking — higher index = worse */
|
|
5
|
-
const STATUS_SEVERITY = [
|
|
6
|
-
"notApplicable",
|
|
7
|
-
"notReviewed",
|
|
8
|
-
"passed",
|
|
9
|
-
"failed",
|
|
10
|
-
"error"
|
|
11
|
-
];
|
|
12
4
|
/** Statuses that count as "passing" for fixed/regressed classification */
|
|
13
5
|
const PASSING_STATUSES = /* @__PURE__ */ new Set(["passed"]);
|
|
14
6
|
/** Statuses that count as "failing" for fixed/regressed classification */
|
|
@@ -18,36 +10,29 @@ const FAILING_STATUSES = /* @__PURE__ */ new Set([
|
|
|
18
10
|
"notReviewed"
|
|
19
11
|
]);
|
|
20
12
|
/**
|
|
21
|
-
* Determine the effective status of a requirement from its results and
|
|
13
|
+
* Determine the effective status of a requirement from its results and
|
|
14
|
+
* overrides, delegating to the canonical shared implementation in
|
|
15
|
+
* `@mitre/hdf-utilities` (see status-determination.md):
|
|
22
16
|
*
|
|
23
|
-
* Priority:
|
|
24
17
|
* 1. impact === 0 → notApplicable (regardless of results)
|
|
25
|
-
* 2.
|
|
26
|
-
* 3.
|
|
18
|
+
* 2. the governing (most recent non-expired) status override's status
|
|
19
|
+
* 3. effectiveStatus field set (and no statusOverrides) → use it
|
|
27
20
|
* 4. Aggregate results using worst-wins
|
|
28
21
|
* 5. Empty results → notReviewed
|
|
29
22
|
*/
|
|
30
23
|
function computeEffectiveStatus(requirement, referenceTimestamp) {
|
|
31
|
-
|
|
32
|
-
const overrides = requirement["statusOverrides"];
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
for (const result of results) {
|
|
44
|
-
const idx = STATUS_SEVERITY.indexOf(result.status);
|
|
45
|
-
if (idx > worstIndex) {
|
|
46
|
-
worstIndex = idx;
|
|
47
|
-
worstStatus = result.status;
|
|
48
|
-
}
|
|
49
|
-
}
|
|
50
|
-
return worstStatus;
|
|
24
|
+
const results = requirement["results"] ?? [];
|
|
25
|
+
const overrides = requirement["statusOverrides"] ?? [];
|
|
26
|
+
return computeEffectiveStatus$1({
|
|
27
|
+
impact: requirement["impact"] ?? NaN,
|
|
28
|
+
effectiveStatus: requirement["effectiveStatus"],
|
|
29
|
+
resultStatuses: results.map((r) => r.status),
|
|
30
|
+
overrides: overrides.map((o) => ({
|
|
31
|
+
status: o.status,
|
|
32
|
+
appliedAt: o.appliedAt,
|
|
33
|
+
expiresAt: o.expiresAt
|
|
34
|
+
}))
|
|
35
|
+
}, referenceTimestamp);
|
|
51
36
|
}
|
|
52
37
|
/**
|
|
53
38
|
* Classify why the status changed between two requirements.
|
|
@@ -65,11 +50,11 @@ function classifyChangeReasons(oldReq, newReq, oldTimestamp, newTimestamp) {
|
|
|
65
50
|
if (newOverrides.length > oldOverrides.length) reasons.push("overrideAdded");
|
|
66
51
|
else if (newOverrides.length < oldOverrides.length) reasons.push("overrideRemoved");
|
|
67
52
|
if (oldTimestamp && newTimestamp && oldOverrides.length > 0) {
|
|
68
|
-
const oldTime =
|
|
69
|
-
const newTime =
|
|
70
|
-
for (const override of oldOverrides) {
|
|
71
|
-
const expiresAt =
|
|
72
|
-
if (expiresAt > oldTime && expiresAt <= newTime) {
|
|
53
|
+
const oldTime = parseTimestamp(oldTimestamp)?.getTime();
|
|
54
|
+
const newTime = parseTimestamp(newTimestamp)?.getTime();
|
|
55
|
+
if (oldTime !== void 0 && newTime !== void 0) for (const override of oldOverrides) {
|
|
56
|
+
const expiresAt = parseTimestamp(override.expiresAt)?.getTime();
|
|
57
|
+
if (expiresAt !== void 0 && expiresAt > oldTime && expiresAt <= newTime) {
|
|
73
58
|
reasons.push("overrideExpired");
|
|
74
59
|
break;
|
|
75
60
|
}
|
|
@@ -2259,6 +2244,496 @@ function computeComponentFieldChanges(oldObj, newObj, trackedFields) {
|
|
|
2259
2244
|
return changes;
|
|
2260
2245
|
}
|
|
2261
2246
|
//#endregion
|
|
2247
|
+
//#region src/effective-checksum.ts
|
|
2248
|
+
/** Maps overrides onto the shared neutral selection shape (applied/expiry
|
|
2249
|
+
* window only; eligibility is passed separately). */
|
|
2250
|
+
function overrideWindows(overrides) {
|
|
2251
|
+
return overrides.map((o) => ({
|
|
2252
|
+
appliedAt: o.appliedAt,
|
|
2253
|
+
expiresAt: o.expiresAt
|
|
2254
|
+
}));
|
|
2255
|
+
}
|
|
2256
|
+
/**
|
|
2257
|
+
* Determine the effective impact of a requirement: the most recently applied
|
|
2258
|
+
* non-expired override carrying an impact value wins (the schema's definition
|
|
2259
|
+
* of effectiveImpact, selected by the shared governing helper); with no
|
|
2260
|
+
* overrides, a stored effectiveImpact field is honored; otherwise the base
|
|
2261
|
+
* impact. (Go parity: ComputeEffectiveImpact in hdf-diff/go/effective_checksum.go.)
|
|
2262
|
+
*/
|
|
2263
|
+
function computeEffectiveImpact(requirement, referenceTimestamp) {
|
|
2264
|
+
const baseImpact = requirement["impact"] ?? 0;
|
|
2265
|
+
const overrides = requirement["statusOverrides"];
|
|
2266
|
+
if (overrides && overrides.length > 0) {
|
|
2267
|
+
const i = governingOverrideIndex(overrideWindows(overrides), (idx) => overrides[idx]?.impact !== void 0, referenceTimestamp);
|
|
2268
|
+
if (i >= 0) return overrides[i].impact.value;
|
|
2269
|
+
return baseImpact;
|
|
2270
|
+
}
|
|
2271
|
+
const effectiveImpact = requirement["effectiveImpact"];
|
|
2272
|
+
if (effectiveImpact !== void 0) return effectiveImpact;
|
|
2273
|
+
return baseImpact;
|
|
2274
|
+
}
|
|
2275
|
+
/**
|
|
2276
|
+
* Return the Override_Type of the governing (most recently applied
|
|
2277
|
+
* non-expired) override, a stored disposition field when no overrides are
|
|
2278
|
+
* present, or null. (Go parity: ComputeDisposition.)
|
|
2279
|
+
*/
|
|
2280
|
+
function computeDisposition(requirement, referenceTimestamp) {
|
|
2281
|
+
const overrides = requirement["statusOverrides"];
|
|
2282
|
+
if (overrides && overrides.length > 0) {
|
|
2283
|
+
const i = governingOverrideIndex(overrideWindows(overrides), () => true, referenceTimestamp);
|
|
2284
|
+
if (i >= 0) return overrides[i]?.type ?? null;
|
|
2285
|
+
return null;
|
|
2286
|
+
}
|
|
2287
|
+
return requirement["disposition"] ?? null;
|
|
2288
|
+
}
|
|
2289
|
+
/**
|
|
2290
|
+
* Hash the resolved effective posture of a requirement: sha256 over the
|
|
2291
|
+
* canonical JSON {"status":<resolved>,"impact":<resolved>,"disposition":<type|null>}.
|
|
2292
|
+
* Flips exactly when the operative status, impact, or disposition changes;
|
|
2293
|
+
* stable under all other document churn. Byte-identical with the Go
|
|
2294
|
+
* implementation (ComputeEffectiveChecksum) — the key order of the canonical
|
|
2295
|
+
* object is part of the contract. Pass the document timestamp as
|
|
2296
|
+
* referenceTimestamp for determinism. A missing or unparseable reference
|
|
2297
|
+
* falls back to the wall clock inside the shared governing-override helper,
|
|
2298
|
+
* so callers that need reproducible output must always supply a valid
|
|
2299
|
+
* timestamp.
|
|
2300
|
+
*/
|
|
2301
|
+
async function computeEffectiveChecksum(requirement, referenceTimestamp) {
|
|
2302
|
+
return {
|
|
2303
|
+
algorithm: "sha256",
|
|
2304
|
+
value: await sha256(JSON.stringify({
|
|
2305
|
+
status: computeEffectiveStatus(requirement, referenceTimestamp),
|
|
2306
|
+
impact: computeEffectiveImpact(requirement, referenceTimestamp),
|
|
2307
|
+
disposition: computeDisposition(requirement, referenceTimestamp)
|
|
2308
|
+
}))
|
|
2309
|
+
};
|
|
2310
|
+
}
|
|
2311
|
+
//#endregion
|
|
2312
|
+
//#region src/change-event.ts
|
|
2313
|
+
/** Batch ChangeReason → event-vocabulary mapping; unmapped reasons are batch-only. */
|
|
2314
|
+
const EVENT_REASON_FOR = {
|
|
2315
|
+
resultChanged: "resultChanged",
|
|
2316
|
+
overrideAdded: "overrideAdded",
|
|
2317
|
+
overrideExpired: "overrideExpired",
|
|
2318
|
+
overrideRemoved: "overrideRemoved",
|
|
2319
|
+
impactChanged: "impactChanged",
|
|
2320
|
+
effectiveImpactChanged: "impactChanged"
|
|
2321
|
+
};
|
|
2322
|
+
function classifyEventReasons(prev, newReq, prevReq, inputs) {
|
|
2323
|
+
const reasons = [];
|
|
2324
|
+
const add = (r) => {
|
|
2325
|
+
if (r && !reasons.includes(r)) reasons.push(r);
|
|
2326
|
+
};
|
|
2327
|
+
if (prevReq) {
|
|
2328
|
+
const prevRef = inputs.prevReferenceTimestamp ?? inputs.referenceTimestamp;
|
|
2329
|
+
for (const r of classifyChangeReasons(prevReq, newReq, prevRef, inputs.referenceTimestamp)) add(EVENT_REASON_FOR[r]);
|
|
2330
|
+
return reasons;
|
|
2331
|
+
}
|
|
2332
|
+
if (computeEffectiveImpact(newReq, inputs.referenceTimestamp) !== prev.effectiveImpact) add("impactChanged");
|
|
2333
|
+
return reasons;
|
|
2334
|
+
}
|
|
2335
|
+
/**
|
|
2336
|
+
* The pure detection kernel (ADR-0005): compare a requirement's resolved
|
|
2337
|
+
* posture against the stored last-value state and emit a
|
|
2338
|
+
* Requirement_Change_Event when it moved, or null when it did not.
|
|
2339
|
+
*
|
|
2340
|
+
* - prev null → state "new" (chain start: null before/priorChecksum)
|
|
2341
|
+
* - newReq null → state "absent" (after null, thin before preserved)
|
|
2342
|
+
* - checksum match → null (no event; the steady-state majority)
|
|
2343
|
+
* - otherwise → fixed/regressed/updated per the effective-status
|
|
2344
|
+
* transition, with the full after requirement as payload
|
|
2345
|
+
*
|
|
2346
|
+
* prevReq (optional) is the full prior requirement when the caller's
|
|
2347
|
+
* materialized state has it; it enables complete changeReasons
|
|
2348
|
+
* classification via the batch classifier, filtered to the event
|
|
2349
|
+
* vocabulary. Without it, only reasons provable from the thin state
|
|
2350
|
+
* (impactChanged) are emitted. Byte-parity with the Go kernel
|
|
2351
|
+
* (ChangeEventFromPrevious) is pinned by shared test vectors.
|
|
2352
|
+
*/
|
|
2353
|
+
async function changeEventFromPrevious(prev, newReq, prevReq, inputs) {
|
|
2354
|
+
if (!prev && !newReq) return null;
|
|
2355
|
+
const envelope = {
|
|
2356
|
+
eventId: inputs.eventId,
|
|
2357
|
+
source: inputs.source,
|
|
2358
|
+
sequence: inputs.sequence,
|
|
2359
|
+
systemRef: inputs.systemRef,
|
|
2360
|
+
componentId: inputs.componentId,
|
|
2361
|
+
requirementId: inputs.requirementId,
|
|
2362
|
+
timestamp: inputs.timestamp,
|
|
2363
|
+
...inputs.schemaRef !== void 0 ? { schemaRef: inputs.schemaRef } : {}
|
|
2364
|
+
};
|
|
2365
|
+
if (!prev) return {
|
|
2366
|
+
...envelope,
|
|
2367
|
+
priorChecksum: null,
|
|
2368
|
+
state: "new",
|
|
2369
|
+
before: null,
|
|
2370
|
+
after: newReq
|
|
2371
|
+
};
|
|
2372
|
+
const before = {
|
|
2373
|
+
effectiveStatus: prev.effectiveStatus,
|
|
2374
|
+
effectiveImpact: prev.effectiveImpact
|
|
2375
|
+
};
|
|
2376
|
+
if (!newReq) return {
|
|
2377
|
+
...envelope,
|
|
2378
|
+
priorChecksum: { ...prev.checksum },
|
|
2379
|
+
state: "absent",
|
|
2380
|
+
before,
|
|
2381
|
+
after: null
|
|
2382
|
+
};
|
|
2383
|
+
if ((await computeEffectiveChecksum(newReq, inputs.referenceTimestamp)).value === prev.checksum.value) return null;
|
|
2384
|
+
const newStatus = computeEffectiveStatus(newReq, inputs.referenceTimestamp);
|
|
2385
|
+
const transition = classifyDiffStatus(prev.effectiveStatus, newStatus);
|
|
2386
|
+
const state = transition === "fixed" || transition === "regressed" ? transition : "updated";
|
|
2387
|
+
const changeReasons = classifyEventReasons(prev, newReq, prevReq, inputs);
|
|
2388
|
+
return {
|
|
2389
|
+
...envelope,
|
|
2390
|
+
priorChecksum: { ...prev.checksum },
|
|
2391
|
+
state,
|
|
2392
|
+
...changeReasons.length > 0 ? { changeReasons } : {},
|
|
2393
|
+
before,
|
|
2394
|
+
after: newReq
|
|
2395
|
+
};
|
|
2396
|
+
}
|
|
2397
|
+
//#endregion
|
|
2398
|
+
//#region src/event-stream-common.ts
|
|
2399
|
+
/** Extract the priorChecksum hex from an event ('' when null/absent). */
|
|
2400
|
+
function eventPriorValue(ev) {
|
|
2401
|
+
return ev["priorChecksum"]?.value ?? "";
|
|
2402
|
+
}
|
|
2403
|
+
/** Effective checksum of a requirement ('' when absent). */
|
|
2404
|
+
async function requirementChecksum(req, referenceTimestamp) {
|
|
2405
|
+
if (!req) return "";
|
|
2406
|
+
return (await computeEffectiveChecksum(req, referenceTimestamp)).value;
|
|
2407
|
+
}
|
|
2408
|
+
/**
|
|
2409
|
+
* Drop duplicate (source, eventId) deliveries — the fold contract's
|
|
2410
|
+
* idempotency key (ADR-0005 §4). Go parity: dedupEvents.
|
|
2411
|
+
*/
|
|
2412
|
+
function dedupEvents(events) {
|
|
2413
|
+
const seen = /* @__PURE__ */ new Set();
|
|
2414
|
+
const deduped = [];
|
|
2415
|
+
for (const ev of events) {
|
|
2416
|
+
if (!ev) continue;
|
|
2417
|
+
const key = `${String(ev["source"])}|${String(ev["eventId"])}`;
|
|
2418
|
+
if (seen.has(key)) continue;
|
|
2419
|
+
seen.add(key);
|
|
2420
|
+
deduped.push(ev);
|
|
2421
|
+
}
|
|
2422
|
+
return deduped;
|
|
2423
|
+
}
|
|
2424
|
+
/**
|
|
2425
|
+
* Group events per entity key, each chain ordered by sequence (eventId
|
|
2426
|
+
* tie-break), keys sorted for deterministic iteration. Go parity:
|
|
2427
|
+
* groupEventChains.
|
|
2428
|
+
*/
|
|
2429
|
+
function groupEventChains(events) {
|
|
2430
|
+
const byKey = /* @__PURE__ */ new Map();
|
|
2431
|
+
for (const ev of events) {
|
|
2432
|
+
const id = ev["requirementId"];
|
|
2433
|
+
const chain = byKey.get(id) ?? [];
|
|
2434
|
+
chain.push(ev);
|
|
2435
|
+
byKey.set(id, chain);
|
|
2436
|
+
}
|
|
2437
|
+
const keys = [...byKey.keys()].sort();
|
|
2438
|
+
for (const [, chain] of byKey) chain.sort((a, b) => {
|
|
2439
|
+
const seqA = a["sequence"];
|
|
2440
|
+
const seqB = b["sequence"];
|
|
2441
|
+
if (seqA !== seqB) return seqA - seqB;
|
|
2442
|
+
return String(a["eventId"]).localeCompare(String(b["eventId"]));
|
|
2443
|
+
});
|
|
2444
|
+
return {
|
|
2445
|
+
byKey,
|
|
2446
|
+
keys
|
|
2447
|
+
};
|
|
2448
|
+
}
|
|
2449
|
+
/**
|
|
2450
|
+
* Walk a per-key chain's priorChecksum links from the seed posture forward,
|
|
2451
|
+
* reporting anomalies through keyWarn. Best-effort: expiry anchored to each
|
|
2452
|
+
* event's occurrence time. Unanchored chains (key not in seed, first event
|
|
2453
|
+
* not new) are left to the caller's application outcome. Go parity:
|
|
2454
|
+
* verifyEventChain.
|
|
2455
|
+
*/
|
|
2456
|
+
async function verifyEventChain(chain, seedReq, inSeed, keyWarn) {
|
|
2457
|
+
const first = chain[0];
|
|
2458
|
+
if (!first) return;
|
|
2459
|
+
if (!inSeed && first["state"] !== "new") return;
|
|
2460
|
+
let expected = "";
|
|
2461
|
+
if (seedReq) expected = await requirementChecksum(seedReq, first["timestamp"]);
|
|
2462
|
+
for (const ev of chain) {
|
|
2463
|
+
const prior = eventPriorValue(ev);
|
|
2464
|
+
if (ev["state"] === "new") {
|
|
2465
|
+
if (inSeed) keyWarn("newOnExisting", "state new for a key already present in the seed");
|
|
2466
|
+
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}"`);
|
|
2468
|
+
expected = await requirementChecksum(ev["after"], ev["timestamp"]);
|
|
2469
|
+
}
|
|
2470
|
+
}
|
|
2471
|
+
//#endregion
|
|
2472
|
+
//#region src/apply-events.ts
|
|
2473
|
+
function findRequirement(doc, id) {
|
|
2474
|
+
const baselines = doc["baselines"] ?? [];
|
|
2475
|
+
for (const baseline of baselines) {
|
|
2476
|
+
const requirements = baseline["requirements"] ?? [];
|
|
2477
|
+
const index = requirements.findIndex((r) => r["id"] === id);
|
|
2478
|
+
if (index >= 0) return {
|
|
2479
|
+
baseline,
|
|
2480
|
+
requirements,
|
|
2481
|
+
index
|
|
2482
|
+
};
|
|
2483
|
+
}
|
|
2484
|
+
return null;
|
|
2485
|
+
}
|
|
2486
|
+
/**
|
|
2487
|
+
* Reassemble the current posture from a seed hdf-results document plus a
|
|
2488
|
+
* batch of requirement-change events (ADR-0005 §§4-7): keyed last-value-wins
|
|
2489
|
+
* by sequence, idempotent via (source, eventId) dedup, tombstone-aware
|
|
2490
|
+
* (absent removes), total over the event-state enum. Delivery order and
|
|
2491
|
+
* duplicates never change the output. The result carries the caller's
|
|
2492
|
+
* generator and a derivation block (seed pinned by content, watermark,
|
|
2493
|
+
* count, asOf) so it can never masquerade as scan evidence. Chain gaps and
|
|
2494
|
+
* anomalies surface as warnings, never as refusal. Go parity:
|
|
2495
|
+
* ApplyChangeEvents.
|
|
2496
|
+
*/
|
|
2497
|
+
async function applyChangeEvents(seedJson, events, inputs) {
|
|
2498
|
+
const doc = JSON.parse(seedJson);
|
|
2499
|
+
const seedChecksum = await sha256(seedJson);
|
|
2500
|
+
const docTimestamp = doc["timestamp"] ?? "";
|
|
2501
|
+
const { byKey, keys } = groupEventChains(dedupEvents(events));
|
|
2502
|
+
const warnings = [];
|
|
2503
|
+
let maxSequence = 0;
|
|
2504
|
+
let maxOccurredMs = Number.NEGATIVE_INFINITY;
|
|
2505
|
+
let asOfFromEvents = "";
|
|
2506
|
+
let eventsApplied = 0;
|
|
2507
|
+
const insertions = [];
|
|
2508
|
+
for (const id of keys) {
|
|
2509
|
+
const chain = byKey.get(id) ?? [];
|
|
2510
|
+
const first = chain[0];
|
|
2511
|
+
const winner = chain[chain.length - 1];
|
|
2512
|
+
if (!first || !winner) continue;
|
|
2513
|
+
const inSeed = findRequirement(doc, id) !== null;
|
|
2514
|
+
let keyWarned = false;
|
|
2515
|
+
const keyWarn = (kind, message) => {
|
|
2516
|
+
if (!keyWarned) {
|
|
2517
|
+
keyWarned = true;
|
|
2518
|
+
warnings.push({
|
|
2519
|
+
requirementId: id,
|
|
2520
|
+
kind,
|
|
2521
|
+
message
|
|
2522
|
+
});
|
|
2523
|
+
}
|
|
2524
|
+
};
|
|
2525
|
+
const located = findRequirement(doc, id);
|
|
2526
|
+
await verifyEventChain(chain, located ? located.requirements[located.index] ?? null : null, inSeed, keyWarn);
|
|
2527
|
+
const verifyLinks = inSeed || first["state"] === "new";
|
|
2528
|
+
const winnerSeq = winner["sequence"];
|
|
2529
|
+
if (winnerSeq > maxSequence) maxSequence = winnerSeq;
|
|
2530
|
+
const occurred = parseTimestamp(winner["timestamp"]);
|
|
2531
|
+
if (occurred !== null && occurred.getTime() > maxOccurredMs) {
|
|
2532
|
+
maxOccurredMs = occurred.getTime();
|
|
2533
|
+
asOfFromEvents = formatTimestamp(occurred);
|
|
2534
|
+
}
|
|
2535
|
+
if (winner["state"] === "absent") {
|
|
2536
|
+
const hit = findRequirement(doc, id);
|
|
2537
|
+
if (hit) {
|
|
2538
|
+
hit.requirements.splice(hit.index, 1);
|
|
2539
|
+
eventsApplied++;
|
|
2540
|
+
} else keyWarn("absentUnknown", "absent event for a key not present in the document");
|
|
2541
|
+
continue;
|
|
2542
|
+
}
|
|
2543
|
+
if (!verifyLinks) keyWarn("chainGap", "non-new chain for a key the seed does not carry");
|
|
2544
|
+
const payload = winner["after"];
|
|
2545
|
+
if (!payload) {
|
|
2546
|
+
keyWarn("chainGap", "winning event carries no applicable after payload");
|
|
2547
|
+
continue;
|
|
2548
|
+
}
|
|
2549
|
+
const hit = findRequirement(doc, id);
|
|
2550
|
+
if (hit) {
|
|
2551
|
+
hit.requirements[hit.index] = structuredClone(payload);
|
|
2552
|
+
eventsApplied++;
|
|
2553
|
+
} else insertions.push({
|
|
2554
|
+
sequence: winnerSeq,
|
|
2555
|
+
id,
|
|
2556
|
+
payload: structuredClone(payload)
|
|
2557
|
+
});
|
|
2558
|
+
}
|
|
2559
|
+
insertions.sort((a, b) => a.sequence !== b.sequence ? a.sequence - b.sequence : a.id.localeCompare(b.id));
|
|
2560
|
+
if (insertions.length > 0) {
|
|
2561
|
+
const baselines = doc["baselines"] ?? [];
|
|
2562
|
+
const firstBaseline = baselines[0];
|
|
2563
|
+
const firstInsertion = insertions[0];
|
|
2564
|
+
if (!firstBaseline || !firstInsertion) throw new Error("seed document has no baselines to insert new requirements into");
|
|
2565
|
+
if (baselines.length > 1) warnings.push({
|
|
2566
|
+
requirementId: firstInsertion.id,
|
|
2567
|
+
kind: "multiBaseline",
|
|
2568
|
+
message: "seed has multiple baselines; new requirements appended to the first"
|
|
2569
|
+
});
|
|
2570
|
+
const requirements = firstBaseline["requirements"] ?? [];
|
|
2571
|
+
for (const ins of insertions) {
|
|
2572
|
+
requirements.push(ins.payload);
|
|
2573
|
+
eventsApplied++;
|
|
2574
|
+
}
|
|
2575
|
+
firstBaseline["requirements"] = requirements;
|
|
2576
|
+
}
|
|
2577
|
+
const asOf = asOfFromEvents !== "" ? asOfFromEvents : docTimestamp;
|
|
2578
|
+
if (asOf === "") throw new Error("cannot derive asOf: no events supplied and the seed document has no timestamp");
|
|
2579
|
+
doc["generator"] = {
|
|
2580
|
+
name: inputs.generator.name,
|
|
2581
|
+
version: inputs.generator.version
|
|
2582
|
+
};
|
|
2583
|
+
doc["timestamp"] = asOf;
|
|
2584
|
+
doc["derivation"] = {
|
|
2585
|
+
seed: {
|
|
2586
|
+
uri: inputs.seedUri,
|
|
2587
|
+
checksum: {
|
|
2588
|
+
algorithm: "sha256",
|
|
2589
|
+
value: seedChecksum
|
|
2590
|
+
}
|
|
2591
|
+
},
|
|
2592
|
+
source: inputs.source,
|
|
2593
|
+
throughSequence: maxSequence,
|
|
2594
|
+
eventsApplied,
|
|
2595
|
+
asOf
|
|
2596
|
+
};
|
|
2597
|
+
return {
|
|
2598
|
+
results: doc,
|
|
2599
|
+
warnings
|
|
2600
|
+
};
|
|
2601
|
+
}
|
|
2602
|
+
//#endregion
|
|
2603
|
+
//#region src/fold-events.ts
|
|
2604
|
+
function findSeedRequirement(doc, id) {
|
|
2605
|
+
const baselines = doc["baselines"] ?? [];
|
|
2606
|
+
for (const baseline of baselines) {
|
|
2607
|
+
const hit = (baseline["requirements"] ?? []).find((r) => r["id"] === id);
|
|
2608
|
+
if (hit) return hit;
|
|
2609
|
+
}
|
|
2610
|
+
return null;
|
|
2611
|
+
}
|
|
2612
|
+
/**
|
|
2613
|
+
* Materialize a change-event batch into a full systemDrift hdf-comparison
|
|
2614
|
+
* against the seed document (ADR-0005 §5): each winning event lifts into the
|
|
2615
|
+
* Requirement_Diff shape the batch engine produces — before from the seed,
|
|
2616
|
+
* after from the event payload, field changes derived by the batch engine's
|
|
2617
|
+
* own computeFieldChanges — under the same fold contract as
|
|
2618
|
+
* applyChangeEvents (dedup, last-value-wins by sequence, tombstone-aware,
|
|
2619
|
+
* warnings never abort). Deterministic: the comparison timestamp is the
|
|
2620
|
+
* latest event occurrence, and seed-side override expiry anchors to the
|
|
2621
|
+
* seed's own timestamp (falling back to the event occurrence when the seed
|
|
2622
|
+
* has none) — never wall clock. Go parity: FoldChangeEventsIntoComparison.
|
|
2623
|
+
*/
|
|
2624
|
+
async function foldChangeEventsIntoComparison(seedJson, events) {
|
|
2625
|
+
const doc = JSON.parse(seedJson);
|
|
2626
|
+
const docTimestamp = doc["timestamp"] ?? "";
|
|
2627
|
+
const { byKey, keys } = groupEventChains(dedupEvents(events));
|
|
2628
|
+
const warnings = [];
|
|
2629
|
+
const diffs = [];
|
|
2630
|
+
let maxOccurredMs = Number.NEGATIVE_INFINITY;
|
|
2631
|
+
let asOfFromEvents = "";
|
|
2632
|
+
let systemRef = "";
|
|
2633
|
+
for (const id of keys) {
|
|
2634
|
+
const chain = byKey.get(id) ?? [];
|
|
2635
|
+
const winner = chain[chain.length - 1];
|
|
2636
|
+
if (!winner) continue;
|
|
2637
|
+
if (systemRef === "") systemRef = winner["systemRef"] ?? "";
|
|
2638
|
+
let keyWarned = false;
|
|
2639
|
+
const keyWarn = (kind, message) => {
|
|
2640
|
+
if (!keyWarned) {
|
|
2641
|
+
keyWarned = true;
|
|
2642
|
+
warnings.push({
|
|
2643
|
+
requirementId: id,
|
|
2644
|
+
kind,
|
|
2645
|
+
message
|
|
2646
|
+
});
|
|
2647
|
+
}
|
|
2648
|
+
};
|
|
2649
|
+
const seedReq = findSeedRequirement(doc, id);
|
|
2650
|
+
await verifyEventChain(chain, seedReq, seedReq !== null, keyWarn);
|
|
2651
|
+
const occurred = parseTimestamp(winner["timestamp"]);
|
|
2652
|
+
if (occurred !== null && occurred.getTime() > maxOccurredMs) {
|
|
2653
|
+
maxOccurredMs = occurred.getTime();
|
|
2654
|
+
asOfFromEvents = formatTimestamp(occurred);
|
|
2655
|
+
}
|
|
2656
|
+
const newTs = occurred !== null ? formatTimestamp(occurred) : winner["timestamp"];
|
|
2657
|
+
const seedRef = docTimestamp !== "" ? docTimestamp : newTs;
|
|
2658
|
+
if (winner["state"] === "absent") {
|
|
2659
|
+
if (!seedReq) {
|
|
2660
|
+
keyWarn("absentUnknown", "absent event for a key not present in the seed");
|
|
2661
|
+
continue;
|
|
2662
|
+
}
|
|
2663
|
+
diffs.push({
|
|
2664
|
+
id,
|
|
2665
|
+
title: seedReq["title"],
|
|
2666
|
+
state: "absent",
|
|
2667
|
+
oldEffectiveStatus: computeEffectiveStatus(seedReq, seedRef),
|
|
2668
|
+
changeReasons: [],
|
|
2669
|
+
oldImpact: seedReq["impact"],
|
|
2670
|
+
fieldChanges: [],
|
|
2671
|
+
before: seedReq,
|
|
2672
|
+
after: null
|
|
2673
|
+
});
|
|
2674
|
+
continue;
|
|
2675
|
+
}
|
|
2676
|
+
const after = winner["after"];
|
|
2677
|
+
if (!after) {
|
|
2678
|
+
keyWarn("chainGap", "winning event carries no applicable after payload");
|
|
2679
|
+
continue;
|
|
2680
|
+
}
|
|
2681
|
+
const newStatus = computeEffectiveStatus(after, newTs);
|
|
2682
|
+
if (!seedReq) {
|
|
2683
|
+
if (winner["state"] !== "new") keyWarn("chainGap", "non-new chain for a key the seed does not carry; lifted as new");
|
|
2684
|
+
diffs.push({
|
|
2685
|
+
id,
|
|
2686
|
+
title: after["title"],
|
|
2687
|
+
state: "new",
|
|
2688
|
+
newEffectiveStatus: newStatus,
|
|
2689
|
+
changeReasons: [],
|
|
2690
|
+
newImpact: after["impact"],
|
|
2691
|
+
fieldChanges: [],
|
|
2692
|
+
before: null,
|
|
2693
|
+
after
|
|
2694
|
+
});
|
|
2695
|
+
continue;
|
|
2696
|
+
}
|
|
2697
|
+
diffs.push({
|
|
2698
|
+
id,
|
|
2699
|
+
title: after["title"] ?? seedReq["title"],
|
|
2700
|
+
state: winner["state"],
|
|
2701
|
+
oldEffectiveStatus: computeEffectiveStatus(seedReq, seedRef),
|
|
2702
|
+
newEffectiveStatus: newStatus,
|
|
2703
|
+
changeReasons: winner["changeReasons"] ?? [],
|
|
2704
|
+
oldImpact: seedReq["impact"],
|
|
2705
|
+
newImpact: after["impact"],
|
|
2706
|
+
fieldChanges: computeFieldChanges(seedReq, after, DEFAULT_TRACKED_FIELDS),
|
|
2707
|
+
before: seedReq,
|
|
2708
|
+
after
|
|
2709
|
+
});
|
|
2710
|
+
}
|
|
2711
|
+
diffs.sort((a, b) => a.id.localeCompare(b.id));
|
|
2712
|
+
const asOf = asOfFromEvents !== "" ? asOfFromEvents : docTimestamp;
|
|
2713
|
+
if (asOf === "") throw new Error("cannot derive a comparison timestamp: no events supplied and the seed document has no timestamp");
|
|
2714
|
+
return {
|
|
2715
|
+
comparison: {
|
|
2716
|
+
formatVersion: "1.0.0",
|
|
2717
|
+
comparisonMode: "systemDrift",
|
|
2718
|
+
timestamp: asOf,
|
|
2719
|
+
...systemRef !== "" ? { systemRef } : {},
|
|
2720
|
+
sources: [{
|
|
2721
|
+
role: "old",
|
|
2722
|
+
label: "Old evaluation"
|
|
2723
|
+
}, {
|
|
2724
|
+
role: "new",
|
|
2725
|
+
label: "New evaluation"
|
|
2726
|
+
}],
|
|
2727
|
+
matching: { primaryStrategy: "exactId" },
|
|
2728
|
+
summary: computeSummary(diffs),
|
|
2729
|
+
baselineDiffs: [],
|
|
2730
|
+
requirementDiffs: diffs,
|
|
2731
|
+
drift: extractDrift(diffs)
|
|
2732
|
+
},
|
|
2733
|
+
warnings
|
|
2734
|
+
};
|
|
2735
|
+
}
|
|
2736
|
+
//#endregion
|
|
2262
2737
|
//#region src/exit-codes.ts
|
|
2263
2738
|
/** GNU diff compatible exit codes (--exit-code mode) */
|
|
2264
2739
|
const EXIT_IDENTICAL = 0;
|
|
@@ -2875,6 +3350,6 @@ function buildPackageMap(packages) {
|
|
|
2875
3350
|
return map;
|
|
2876
3351
|
}
|
|
2877
3352
|
//#endregion
|
|
2878
|
-
export { EXIT_DETAILED_BASELINE_CHANGED, EXIT_DETAILED_DRIFT_ONLY, EXIT_DETAILED_ERROR, EXIT_DETAILED_FIXES_ONLY, EXIT_DETAILED_IDENTICAL, EXIT_DETAILED_MIXED, EXIT_DETAILED_REGRESSIONS_ONLY, EXIT_DIFFERENCES, EXIT_ERROR, EXIT_IDENTICAL, classifyChangeReasons, classifyDiffStatus, computeDetailedExitCode, computeEffectiveStatus, computeExitCode, computeSummary, createCciMatchStrategy, createExactIdStrategy, createFuzzyTitleStrategy, createMappedIdStrategy, createSrgCciTiebreakStrategy, createSrgDeterministicStrategy, createVendorFuzzyTitleStrategy, diffBaselines, diffHdf, diffSboms, diffSystems, isV1Format, jaccardSimilarity, levenshteinDistance, matchRequirements, normalizeToV2, normalizedLevenshtein, render, renderCsv, renderJson, renderMarkdown, renderTerminal, tokenize, validateComparison };
|
|
3353
|
+
export { EXIT_DETAILED_BASELINE_CHANGED, EXIT_DETAILED_DRIFT_ONLY, EXIT_DETAILED_ERROR, EXIT_DETAILED_FIXES_ONLY, EXIT_DETAILED_IDENTICAL, EXIT_DETAILED_MIXED, EXIT_DETAILED_REGRESSIONS_ONLY, EXIT_DIFFERENCES, EXIT_ERROR, EXIT_IDENTICAL, applyChangeEvents, changeEventFromPrevious, classifyChangeReasons, classifyDiffStatus, computeDetailedExitCode, computeDisposition, computeEffectiveChecksum, computeEffectiveImpact, computeEffectiveStatus, computeExitCode, computeSummary, createCciMatchStrategy, createExactIdStrategy, createFuzzyTitleStrategy, createMappedIdStrategy, createSrgCciTiebreakStrategy, createSrgDeterministicStrategy, createVendorFuzzyTitleStrategy, diffBaselines, diffHdf, diffSboms, diffSystems, foldChangeEventsIntoComparison, isV1Format, jaccardSimilarity, levenshteinDistance, matchRequirements, normalizeToV2, normalizedLevenshtein, render, renderCsv, renderJson, renderMarkdown, renderTerminal, tokenize, validateComparison };
|
|
2879
3354
|
|
|
2880
3355
|
//# sourceMappingURL=index.js.map
|