@mitre/hdf-diff 2.0.0

package/dist/sbom.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SBOM comparison for the HDF diff engine.
+ *
+ * Compares two SBOM documents (CycloneDX or SPDX JSON) and produces
+ * package-level diffs: added, removed, updated, unchanged packages.
+ *
+ * Format auto-detection:
+ * - CycloneDX: has `bomFormat: "CycloneDX"`, packages in `components[]`
+ * - SPDX: has `spdxVersion`, packages in `packages[]`
+ */
+/**
+ * The comparison result for a single package between two SBOMs.
+ */
+export interface PackageDiff {
+    purl: string;
+    name: string;
+    state: 'added' | 'removed' | 'updated' | 'unchanged';
+    oldVersion?: string;
+    newVersion?: string;
+    licenses?: string[];
+}
+/**
+ * The complete result of comparing two SBOM documents.
+ */
+export interface SbomDiffResult {
+    packageDiffs: PackageDiff[];
+    added: number;
+    removed: number;
+    updated: number;
+    unchanged: number;
+}
+/**
+ * Compare two SBOM documents (CycloneDX or SPDX JSON strings) and return
+ * package-level diffs.
+ *
+ * @param oldJson - JSON string of the old SBOM document
+ * @param newJson - JSON string of the new SBOM document
+ * @returns Structured diff result with per-package state and aggregate counts
+ * @throws Error if either input is not valid JSON or not a recognized SBOM format
+ */
+export declare function diffSboms(oldJson: string, newJson: string): SbomDiffResult;
+//# sourceMappingURL=sbom.d.ts.map

package/dist/sbom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom.d.ts","sourceRoot":"","sources":["../src/sbom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CA2E1E"}

package/dist/sbom.js

@@ -0,0 +1,203 @@
+/**
+ * SBOM comparison for the HDF diff engine.
+ *
+ * Compares two SBOM documents (CycloneDX or SPDX JSON) and produces
+ * package-level diffs: added, removed, updated, unchanged packages.
+ *
+ * Format auto-detection:
+ * - CycloneDX: has `bomFormat: "CycloneDX"`, packages in `components[]`
+ * - SPDX: has `spdxVersion`, packages in `packages[]`
+ */
+/**
+ * Compare two SBOM documents (CycloneDX or SPDX JSON strings) and return
+ * package-level diffs.
+ *
+ * @param oldJson - JSON string of the old SBOM document
+ * @param newJson - JSON string of the new SBOM document
+ * @returns Structured diff result with per-package state and aggregate counts
+ * @throws Error if either input is not valid JSON or not a recognized SBOM format
+ */
+export function diffSboms(oldJson, newJson) {
+    const oldParsed = JSON.parse(oldJson);
+    const newParsed = JSON.parse(newJson);
+    const oldPackages = extractPackages(oldParsed);
+    const newPackages = extractPackages(newParsed);
+    const oldMap = buildPackageMap(oldPackages);
+    const newMap = buildPackageMap(newPackages);
+    const diffs = [];
+    const seen = new Set();
+    // Check old packages against new
+    for (const [key, oldPkg] of oldMap) {
+        seen.add(key);
+        const newPkg = newMap.get(key);
+        if (newPkg) {
+            if (oldPkg.version !== newPkg.version) {
+                diffs.push({
+                    purl: newPkg.purl || newPkg.name,
+                    name: newPkg.name,
+                    state: 'updated',
+                    oldVersion: oldPkg.version,
+                    newVersion: newPkg.version,
+                    licenses: newPkg.licenses.length > 0 ? newPkg.licenses : undefined,
+                });
+            }
+            else {
+                diffs.push({
+                    purl: oldPkg.purl || oldPkg.name,
+                    name: oldPkg.name,
+                    state: 'unchanged',
+                });
+            }
+        }
+        else {
+            diffs.push({
+                purl: oldPkg.purl || oldPkg.name,
+                name: oldPkg.name,
+                state: 'removed',
+                oldVersion: oldPkg.version,
+            });
+        }
+    }
+    // Check for added packages
+    for (const [key, newPkg] of newMap) {
+        if (!seen.has(key)) {
+            diffs.push({
+                purl: newPkg.purl || newPkg.name,
+                name: newPkg.name,
+                state: 'added',
+                newVersion: newPkg.version,
+                licenses: newPkg.licenses.length > 0 ? newPkg.licenses : undefined,
+            });
+        }
+    }
+    // Sort by name for deterministic output
+    diffs.sort((a, b) => a.name.localeCompare(b.name));
+    // Count states
+    let added = 0;
+    let removed = 0;
+    let updated = 0;
+    let unchanged = 0;
+    for (const d of diffs) {
+        switch (d.state) {
+            case 'added':
+                added++;
+                break;
+            case 'removed':
+                removed++;
+                break;
+            case 'updated':
+                updated++;
+                break;
+            case 'unchanged':
+                unchanged++;
+                break;
+        }
+    }
+    return { packageDiffs: diffs, added, removed, updated, unchanged };
+}
+/**
+ * Extract packages from an SBOM document, auto-detecting the format.
+ */
+function extractPackages(doc) {
+    if (doc['bomFormat'] === 'CycloneDX') {
+        return extractCycloneDXPackages(doc);
+    }
+    if (typeof doc['spdxVersion'] === 'string') {
+        return extractSPDXPackages(doc);
+    }
+    throw new Error('Unrecognized SBOM format: expected CycloneDX (bomFormat) or SPDX (spdxVersion)');
+}
+/**
+ * Extract packages from a CycloneDX document.
+ * Reads components[] with purl, name, version fields.
+ */
+function extractCycloneDXPackages(doc) {
+    const components = doc['components'];
+    if (!Array.isArray(components)) {
+        return [];
+    }
+    return components.map((comp) => {
+        const licenses = extractCycloneDXLicenses(comp);
+        return {
+            purl: comp['purl'] ?? '',
+            name: comp['name'] ?? '',
+            version: comp['version'] ?? '',
+            licenses,
+        };
+    });
+}
+/**
+ * Extract license strings from a CycloneDX component.
+ * CycloneDX licenses can be in `licenses[].license.id` or `licenses[].license.name`.
+ */
+function extractCycloneDXLicenses(comp) {
+    const licensesArr = comp['licenses'];
+    if (!Array.isArray(licensesArr)) {
+        return [];
+    }
+    const result = [];
+    for (const entry of licensesArr) {
+        const license = entry['license'];
+        if (license) {
+            const id = license['id'];
+            const name = license['name'];
+            if (id) {
+                result.push(id);
+            }
+            else if (name) {
+                result.push(name);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Extract packages from an SPDX document.
+ * Reads packages[] with name, versionInfo, and externalRefs (for PURL).
+ */
+function extractSPDXPackages(doc) {
+    const packages = doc['packages'];
+    if (!Array.isArray(packages)) {
+        return [];
+    }
+    return packages.map((pkg) => {
+        const purl = extractSPDXPurl(pkg);
+        const license = pkg['licenseConcluded'] ?? pkg['licenseDeclared'] ?? '';
+        return {
+            purl,
+            name: pkg['name'] ?? '',
+            version: pkg['versionInfo'] ?? '',
+            licenses: license && license !== 'NOASSERTION' ? [license] : [],
+        };
+    });
+}
+/**
+ * Extract a PURL from an SPDX package's externalRefs array.
+ */
+function extractSPDXPurl(pkg) {
+    const refs = pkg['externalRefs'];
+    if (!Array.isArray(refs)) {
+        return '';
+    }
+    for (const ref of refs) {
+        const refType = ref['referenceType'];
+        if (refType === 'purl') {
+            return ref['referenceLocator'] ?? '';
+        }
+    }
+    return '';
+}
+/**
+ * Build a lookup map of packages indexed by name (version-independent key).
+ */
+function buildPackageMap(packages) {
+    const map = new Map();
+    for (const pkg of packages) {
+        const key = pkg.name || pkg.purl;
+        if (key) {
+            map.set(key, pkg);
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=sbom.js.map

package/dist/sbom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sbom.js","sourceRoot":"","sources":["../src/sbom.ts"],"names":[],"mappings":"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"}

package/dist/status.d.ts

@@ -0,0 +1,27 @@
+import type { ChangeReason, RequirementState } from './types.js';
+/**
+ * Determine the effective status of a requirement from its results and overrides.
+ *
+ * Priority:
+ * 1. impact === 0 → notApplicable (regardless of results)
+ * 2. effectiveStatus field set (and no statusOverrides) → use it
+ * 3. Non-expired statusOverrides → use first non-expired
+ * 4. Aggregate results using worst-wins
+ * 5. Empty results → notReviewed
+ */
+export declare function computeEffectiveStatus(requirement: Record<string, unknown>, referenceTimestamp?: string): string;
+/**
+ * Classify why the status changed between two requirements.
+ * Returns an array of change reasons (a status change can have multiple causes).
+ */
+export declare function classifyChangeReasons(oldReq: Record<string, unknown>, newReq: Record<string, unknown>, oldTimestamp?: string, newTimestamp?: string): ChangeReason[];
+/**
+ * Classify the overall diff status based on old and new effective statuses.
+ *
+ * - If old is failing and new is passing → 'fixed'
+ * - If old is passing and new is failing → 'regressed'
+ * - If statuses are equal → 'unchanged'
+ * - Otherwise → 'updated'
+ */
+export declare function classifyDiffStatus(oldEffectiveStatus: string, newEffectiveStatus: string): RequirementState;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA0BjE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,kBAAkB,CAAC,EAAE,MAAM,GAC1B,MAAM,CAyCR;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,YAAY,EAAE,CAuDhB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,GACzB,gBAAgB,CAkBlB"}

package/dist/status.js

@@ -0,0 +1,137 @@
+/** Status severity ranking — higher index = worse */
+const STATUS_SEVERITY = [
+    'notApplicable',
+    'notReviewed',
+    'passed',
+    'failed',
+    'error',
+];
+/** Statuses that count as "passing" for fixed/regressed classification */
+const PASSING_STATUSES = new Set(['passed']);
+/** Statuses that count as "failing" for fixed/regressed classification */
+const FAILING_STATUSES = new Set(['failed', 'error', 'notReviewed']);
+/**
+ * Determine the effective status of a requirement from its results and overrides.
+ *
+ * Priority:
+ * 1. impact === 0 → notApplicable (regardless of results)
+ * 2. effectiveStatus field set (and no statusOverrides) → use it
+ * 3. Non-expired statusOverrides → use first non-expired
+ * 4. Aggregate results using worst-wins
+ * 5. Empty results → notReviewed
+ */
+export function computeEffectiveStatus(requirement, referenceTimestamp) {
+    const impact = requirement['impact'];
+    if (impact === 0) {
+        return 'notApplicable';
+    }
+    const overrides = requirement['statusOverrides'];
+    if (overrides && overrides.length > 0) {
+        const refTime = referenceTimestamp ? new Date(referenceTimestamp).getTime() : Date.now();
+        for (const override of overrides) {
+            const expiresAt = new Date(override.expiresAt).getTime();
+            if (expiresAt > refTime) {
+                return override.status;
+            }
+        }
+        // All overrides expired — fall through to results
+    }
+    // If effectiveStatus is set and there are no overrides, use it
+    const effectiveStatus = requirement['effectiveStatus'];
+    if (effectiveStatus && (!overrides || overrides.length === 0)) {
+        return effectiveStatus;
+    }
+    const results = requirement['results'];
+    if (!results || results.length === 0) {
+        return 'notReviewed';
+    }
+    // Worst-wins: find the status with the highest severity index
+    let worstIndex = -1;
+    let worstStatus = 'notReviewed';
+    for (const result of results) {
+        const idx = STATUS_SEVERITY.indexOf(result.status);
+        if (idx > worstIndex) {
+            worstIndex = idx;
+            worstStatus = result.status;
+        }
+    }
+    return worstStatus;
+}
+/**
+ * Classify why the status changed between two requirements.
+ * Returns an array of change reasons (a status change can have multiple causes).
+ */
+export function classifyChangeReasons(oldReq, newReq, oldTimestamp, newTimestamp) {
+    const reasons = [];
+    // Check result status changes
+    const oldResults = oldReq['results'] ?? [];
+    const newResults = newReq['results'] ?? [];
+    const oldResultStatuses = oldResults.map((r) => r.status).sort();
+    const newResultStatuses = newResults.map((r) => r.status).sort();
+    if (JSON.stringify(oldResultStatuses) !== JSON.stringify(newResultStatuses)) {
+        reasons.push('resultChanged');
+    }
+    // Check override changes
+    const oldOverrides = oldReq['statusOverrides'] ?? [];
+    const newOverrides = newReq['statusOverrides'] ?? [];
+    if (newOverrides.length > oldOverrides.length) {
+        reasons.push('overrideAdded');
+    }
+    else if (newOverrides.length < oldOverrides.length) {
+        reasons.push('overrideRemoved');
+    }
+    // Check for override expiration between scans
+    if (oldTimestamp && newTimestamp && oldOverrides.length > 0) {
+        const oldTime = new Date(oldTimestamp).getTime();
+        const newTime = new Date(newTimestamp).getTime();
+        for (const override of oldOverrides) {
+            const expiresAt = new Date(override.expiresAt).getTime();
+            if (expiresAt > oldTime && expiresAt <= newTime) {
+                reasons.push('overrideExpired');
+                break; // Only report once
+            }
+        }
+    }
+    // Check impact changes
+    const oldImpact = oldReq['impact'];
+    const newImpact = newReq['impact'];
+    if (oldImpact !== newImpact) {
+        reasons.push('impactChanged');
+    }
+    // Check baseline metadata changes (tags, descriptions, title)
+    const oldTags = JSON.stringify(oldReq['tags'] ?? {});
+    const newTags = JSON.stringify(newReq['tags'] ?? {});
+    const oldDescs = JSON.stringify(oldReq['descriptions'] ?? []);
+    const newDescs = JSON.stringify(newReq['descriptions'] ?? []);
+    const oldTitle = oldReq['title'];
+    const newTitle = newReq['title'];
+    if (oldTags !== newTags || oldDescs !== newDescs || oldTitle !== newTitle) {
+        reasons.push('metadataChanged');
+    }
+    return reasons;
+}
+/**
+ * Classify the overall diff status based on old and new effective statuses.
+ *
+ * - If old is failing and new is passing → 'fixed'
+ * - If old is passing and new is failing → 'regressed'
+ * - If statuses are equal → 'unchanged'
+ * - Otherwise → 'updated'
+ */
+export function classifyDiffStatus(oldEffectiveStatus, newEffectiveStatus) {
+    if (oldEffectiveStatus === newEffectiveStatus) {
+        return 'unchanged';
+    }
+    const oldIsFailing = FAILING_STATUSES.has(oldEffectiveStatus);
+    const newIsPassing = PASSING_STATUSES.has(newEffectiveStatus);
+    const oldIsPassing = PASSING_STATUSES.has(oldEffectiveStatus);
+    const newIsFailing = FAILING_STATUSES.has(newEffectiveStatus);
+    if (oldIsFailing && newIsPassing) {
+        return 'fixed';
+    }
+    if (oldIsPassing && newIsFailing) {
+        return 'regressed';
+    }
+    return 'updated';
+}
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"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"}

package/dist/summary.d.ts

@@ -0,0 +1,6 @@
+import type { ComparisonSummary, RequirementDiff } from './types.js';
+/**
+ * Compute summary counts from an array of RequirementDiff entries.
+ */
+export declare function computeSummary(requirements: RequirementDiff[]): ComparisonSummary;
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAErE;;GAEG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,eAAe,EAAE,GAAG,iBAAiB,CA4CjF"}

package/dist/summary.js

@@ -0,0 +1,47 @@
+/**
+ * Compute summary counts from an array of RequirementDiff entries.
+ */
+export function computeSummary(requirements) {
+    const summary = {
+        fixed: 0,
+        regressed: 0,
+        new: 0,
+        absent: 0,
+        unchanged: 0,
+        updated: 0,
+        total: requirements.length,
+        matchedCount: 0,
+        unmatchedOldCount: 0,
+        unmatchedNewCount: 0,
+    };
+    for (const req of requirements) {
+        switch (req.state) {
+            case 'fixed':
+                summary.fixed++;
+                summary.matchedCount++;
+                break;
+            case 'regressed':
+                summary.regressed++;
+                summary.matchedCount++;
+                break;
+            case 'new':
+                summary.new++;
+                summary.unmatchedNewCount++;
+                break;
+            case 'absent':
+                summary.absent++;
+                summary.unmatchedOldCount++;
+                break;
+            case 'unchanged':
+                summary.unchanged++;
+                summary.matchedCount++;
+                break;
+            case 'updated':
+                summary.updated++;
+                summary.matchedCount++;
+                break;
+        }
+    }
+    return summary;
+}
+//# sourceMappingURL=summary.js.map

package/dist/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../src/summary.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,YAA+B;IAC5D,MAAM,OAAO,GAAsB;QACjC,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,GAAG,EAAE,CAAC;QACN,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,YAAY,CAAC,MAAM;QAC1B,YAAY,EAAE,CAAC;QACf,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;KACrB,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,QAAQ,GAAG,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,OAAO;gBACV,OAAO,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM;YACR,KAAK,WAAW;gBACd,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpB,OAAO,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM;YACR,KAAK,KAAK;gBACR,OAAO,CAAC,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,iBAAiB,EAAE,CAAC;gBAC5B,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,CAAC,MAAM,EAAE,CAAC;gBACjB,OAAO,CAAC,iBAAiB,EAAE,CAAC;gBAC5B,MAAM;YACR,KAAK,WAAW;gBACd,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpB,OAAO,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM;YACR,KAAK,SAAS;gBACZ,OAAO,CAAC,OAAO,EAAE,CAAC;gBAClB,OAAO,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}