// Unit tests for compare-flow.ts (KAR-942 / Multi-QAF-Programm P3.1). // // FIXTURE-DATEN-REGEL (same discipline as synthetic-fixtures.ts's own header // comment, KAR-929 adversarial review F4 — merge-blocker class): every code, // number, label, and cell reference below is FREE INVENTION, not lifted from // any real analyzed workbook. Real-file end-to-end coverage (Datei 3 vs. // Datei 4, self-compare) lives in compare-flow.real-files.test.ts (env-gated). // // Scenarios covered: (1) self-compare of every synthetic container fixture // produces a zero-finding, reviewRequired:false result; (2) a genuine // cross-fixture diff produces reviewRequired:true with the expected floor // reasons; (3) a persisted VariantMatchOverride wins over the automatic // cascade and is reflected in matchResult; (4) a drifted override is dropped // and additively sets reviewRequired/reviewRequiredReasons without // suppressing anything diffContainers itself already computed; (5) an empty // overrides array is a true no-op (same discipline // applyFieldMappingOverrides established); (6) the result round-trips // byte-for-byte through the versioned JSON envelope (persist -> reopen, // KAR-942's own "reopen without re-parse" requirement); (7) // multiQafBaselineStatusFor maps reviewRequired onto the existing // qaf_comparison.baseline_status enum, both directions. import { describe, expect, it } from 'vitest' import { buildCompositeCanonicalKey, makeDimensionValue } from '../identity' import type { MultiQafContainer, VariantDefinition, VariantDimensions } from '../types' import { deserializeMultiQafContainer, serializeMultiQafContainer } from '../serialization' import type { VariantMatchOverride } from '../variant-matcher' import { deserializeMultiQafComparisonResult, multiQafBaselineStatusFor, MULTI_QAF_COMPARISON_RESULT_VERSION, runMultiQafCompareFlow, serializeMultiQafComparisonResult, } from '../compare-flow' import { buildMultiRowHeaderFixture, buildSharedManufacturingFixture, buildSplitColumnFixture, buildWideSlotFixture, SYNTHETIC_FIXTURES, } from './synthetic-fixtures' // ── Minimal fixture builders (same shape/defaults as container-differ.test.ts's // own local builders — kept local per this repo's established "each module's // test file defines its own minimal fixtures" convention). ────────────────── function dims(entries: Record): VariantDimensions { const out: Record> = {} for (const [k, v] of Object.entries(entries)) out[k] = makeDimensionValue(v) return out } function variant(id: string, dimEntries: Record, overrides: Partial = {}): VariantDefinition { const dimensions = overrides.dimensions ?? dims(dimEntries) const labels = overrides.originalLabels ?? [`Label ${id}`] return { stableInternalId: id, originalColumn: overrides.originalColumn ?? 'Q', originalColumnIndex: overrides.originalColumnIndex ?? 17, originalVariantNumber: overrides.originalVariantNumber ?? '1', originalLabels: labels, normalizedLabels: overrides.normalizedLabels ?? labels.map((l) => l.toLowerCase()), compositeCanonicalKey: overrides.compositeCanonicalKey ?? buildCompositeCanonicalKey(dimensions, id), dimensions, annualVolume: overrides.annualVolume ?? 1000, peakVolume: overrides.peakVolume ?? null, lifetimeVolume: overrides.lifetimeVolume ?? null, currency: overrides.currency ?? 'EUR', activeState: overrides.activeState ?? 'active', sourceReferences: overrides.sourceReferences ?? [ { sheet: 'Zusammenfassung', cell: `${overrides.originalColumn ?? 'Q'}2`, row: 1, column: overrides.originalColumnIndex ?? 17 }, ], confidence: overrides.confidence ?? 0.9, } } function emptyContainer(overrides: Partial = {}): MultiQafContainer { return { sourceWorkbook: { fileName: null, fileHash: null, sheetNames: [], hiddenSheetNames: [] }, detectedTemplateFamily: 'unknown', multiQafVersion: null, underlyingQafVersion: null, language: 'unknown', currencies: [], sharedMetadata: {}, variantDimensions: [], activeVariants: [], inactiveVariants: [], auxiliaryScenarios: [], helperColumns: [], sharedMaterialMaster: [], sharedManufacturingProfiles: [], sharedToolingData: [], setupCostProfiles: [], variantProfileBindings: [], summaryAggregation: { perVariant: [], formulaLineageNotes: [] }, templateFingerprint: { family: 'unknown', structuralHash: null, variantColumnCount: 0, headerRowCount: 0, knownProfile: null, classification: null }, warnings: [], confidence: 0.5, summaryMoneyRowsByVariant: {}, ...overrides, } } function snapshot(v: VariantDefinition) { return { compositeCanonicalKey: v.compositeCanonicalKey, dimensions: v.dimensions } } // ── (1) Self-compare: zero findings, reviewRequired false ────────────────── describe.each(Object.entries(SYNTHETIC_FIXTURES))('runMultiQafCompareFlow — self-compare: %s', (_name, build) => { it('produces a zero-finding result with reviewRequired false, matching the container-differ.ts self-diff anchor', () => { const alt = build() const neu = deserializeMultiQafContainer(serializeMultiQafContainer(alt)) const result = runMultiQafCompareFlow(alt, neu) expect(result.modelVersion).toBe(MULTI_QAF_COMPARISON_RESULT_VERSION) expect(result.droppedOverrides).toEqual([]) // NOTE (verified empirically, NOT a KAR-942 bug — inherent, documented // variant-matcher.ts behavior): a fully-empty "reserved" slot (no // identity at all — types.ts's own `VariantActiveState` doc: "no // identity at all") carries no dimension data to match on, so even a // byte-identical self-copy cannot pair reserved slot N on one side with // reserved slot N on the other (Master-Prompt §9 forbids using column // position as identity) — the wideSlot fixture's 13 fully-empty slots // (10-analyse-mx.md C's real "13 von 25 nutzlos-leer" pattern) surface // as a SYMMETRIC added/removed set (same originalVariantNumbers on both // sides, net commercial impact zero — no variant with actual DATA is // ever lost or fabricated), not as a "clean" empty diff. Asserted as "no // NET change" (same multiset of position numbers on both sides) rather // than "always literally empty", which holds for every fixture WITHOUT // reserved slots and is still a meaningful self-diff-safety property for // the one that has them. const addedNums = result.containerDiff.variants.added.map((a) => a.neu.originalVariantNumber).sort() const removedNums = result.containerDiff.variants.removed.map((a) => a.alt.originalVariantNumber).sort() expect(addedNums).toEqual(removedNums) expect(result.containerDiff.variants.uncertainMatches).toEqual([]) expect(result.materialDiff.sharedComponents.unitCostValueChanges).toEqual([]) expect(result.materialDiff.variantAllocation.findings).toEqual([]) expect(result.profileDiff.added).toEqual([]) expect(result.profileDiff.removed).toEqual([]) // KAR-945 / KAR-942 adversarial-review F2 fix (13.07.2026): profile- // differ.ts's diffValueEntry used to mark every NON-NUMERIC profile-value // field 'nicht_berechenbar' unconditionally, without an equality check // first (unlike the numeric path, which short-circuits on `status === // 'konstant'`) — a profile carrying a string field (e.g. this fixture's // `site`) therefore always produced a componentValueChanges entry on a // byte-identical self-compare, even though nothing changed. Fixed: // diffValueEntry now compares non-numeric values (trimmed/normalized) // before deciding the status, so a byte-identical self-compare produces // NO componentValueChanges findings at all — strictly empty, same as the // numeric-only fixtures always asserted. expect(result.profileDiff.componentValueChanges).toEqual([]) expect(result.profileDiff.totalChanges).toEqual([]) expect(result.reviewRequired).toBe(false) expect(result.reviewRequiredReasons).toEqual([]) expect(multiQafBaselineStatusFor(result)).toBe('ok') // KAR-951 — summaryTotalsDiff is a peer of materialDiff/profileDiff: // always populated, never 'changed' on a byte-identical self-compare. expect(result.summaryTotalsDiff).not.toBeNull() expect(result.summaryTotalsDiff!.findings.filter((f) => f.state === 'changed')).toEqual([]) // reconcileContainer runs once per side over EVERY active+inactive // variant of that side — the self-compare's two sides have the same // variant count, so the two reconciliation arrays are the same length. expect(result.reconciliation.alt.length).toBe(result.reconciliation.neu.length) }) }) // ── (2) Cross-fixture diff: genuinely different containers ───────────────── describe('runMultiQafCompareFlow — cross-fixture diff', () => { it('two structurally unrelated synthetic containers produce reviewRequired true with the uncertain/added/removed floor from diffContainers', () => { const alt = buildWideSlotFixture() const neu = buildSharedManufacturingFixture() const result = runMultiQafCompareFlow(alt, neu) // No shared identity between these two fixtures' variants — every alt // variant is 'removed' or 'uncertain', every neu variant is 'added' or // 'uncertain'; never a spurious 'matched'. const matchedCount = result.matchResult.filter((r) => r.kind === 'matched').length expect(matchedCount).toBe(0) expect(result.containerDiff.variants.removed.length).toBeGreaterThan(0) expect(result.containerDiff.variants.added.length).toBeGreaterThan(0) // diffContainers' own floor is never suppressed by this module. expect(result.reviewRequired).toBe(result.containerDiff.reviewRequired) expect(result.reviewRequired).toBe(true) expect(result.reviewRequiredReasons).toEqual(result.containerDiff.reviewRequiredReasons) expect(multiQafBaselineStatusFor(result)).toBe('baseline_review') }) it('every result field is independently populated for two different real-pattern fixtures (shape smoke test)', () => { const alt = buildMultiRowHeaderFixture() const neu = buildSplitColumnFixture() const result = runMultiQafCompareFlow(alt, neu) expect(result.matchResult.length).toBeGreaterThan(0) expect(result.containerDiff).toBeDefined() expect(result.materialDiff).toBeDefined() expect(result.profileDiff).toBeDefined() expect(result.reconciliation.alt.length).toBe(alt.activeVariants.length + alt.inactiveVariants.length) expect(result.reconciliation.neu.length).toBe(neu.activeVariants.length + neu.inactiveVariants.length) }) }) // ── (3)/(4)/(5) VariantMatchOverride application ──────────────────────────── describe('runMultiQafCompareFlow — persisted VariantMatchOverride application', () => { function twoUnrelatedContainers(): { alt: MultiQafContainer; neu: MultiQafContainer } { // Deliberately disjoint dimensions so the automatic cascade produces NO // match at all on its own (both sides end up unmatched_left/unmatched_right). const altVariant = variant('ALT-1', { vehicle: 'zz1', driveType: 'fwd', region: 'apac' }) const neuVariant = variant('NEU-1', { vehicle: 'zz9', driveType: 'rwd', region: 'emea' }) const alt = emptyContainer({ activeVariants: [altVariant] }) const neu = emptyContainer({ activeVariants: [neuVariant] }) return { alt, neu } } it('an active override wins over an automatic cascade that would otherwise leave both sides unmatched', () => { const { alt, neu } = twoUnrelatedContainers() const override: VariantMatchOverride = { left: snapshot(alt.activeVariants[0]!), right: snapshot(neu.activeVariants[0]!), decision: 'matched', note: 'Reviewer confirmed ALT-1 <-> NEU-1 despite no structural overlap.', setBy: 'reviewer@example.com', setAt: '2026-07-13T00:00:00Z', } const withoutOverride = runMultiQafCompareFlow(alt, neu) expect(withoutOverride.matchResult.every((r) => r.kind !== 'matched')).toBe(true) const withOverride = runMultiQafCompareFlow(alt, neu, { variantMatchOverrides: [override] }) expect(withOverride.droppedOverrides).toEqual([]) const matched = withOverride.matchResult.filter((r): r is Extract => r.kind === 'matched') expect(matched).toHaveLength(1) expect(matched[0]).toMatchObject({ leftId: 'ALT-1', rightId: 'NEU-1', stage: 'manual_override' }) // The forced match removes the pair from containerDiff's added/removed sets. expect(withOverride.containerDiff.variants.added).toEqual([]) expect(withOverride.containerDiff.variants.removed).toEqual([]) }) it('a drifted override is dropped, additively sets reviewRequired/reviewRequiredReasons, and never suppresses diffContainers own floor', () => { const { alt, neu } = twoUnrelatedContainers() const driftedOverride: VariantMatchOverride = { left: { compositeCanonicalKey: 'vehicle=zz1|driveType=fwd|region=apac|no-longer-current', dimensions: dims({ vehicle: 'zz1', driveType: 'fwd', region: 'apac', extra: 'drifted' }) }, right: snapshot(neu.activeVariants[0]!), decision: 'matched', note: null, setBy: 'reviewer@example.com', setAt: '2026-07-13T00:00:00Z', } const result = runMultiQafCompareFlow(alt, neu, { variantMatchOverrides: [driftedOverride] }) expect(result.droppedOverrides).toHaveLength(1) expect(result.droppedOverrides[0]!.status).toBe('dropped_on_drift') expect(result.reviewRequiredReasons).toContain('match_overrides_dropped_on_drift') expect(result.reviewRequired).toBe(true) // The automatic cascade still ran on the un-overridden pair (no shared // identity here, so it stays unmatched — never silently forced). expect(result.matchResult.every((r) => r.kind !== 'matched')).toBe(true) }) it('an empty overrides array is a true no-op (byte-identical result to omitting the option)', () => { const { alt, neu } = twoUnrelatedContainers() const a = runMultiQafCompareFlow(alt, neu) const b = runMultiQafCompareFlow(alt, neu, { variantMatchOverrides: [] }) expect(b).toEqual(a) }) }) // ── summaryTotalsDiff wiring (KAR-951) ────────────────────────────────────── describe('runMultiQafCompareFlow — summaryTotalsDiff (KAR-951)', () => { function twoMatchedVariants(): { alt: MultiQafContainer; neu: MultiQafContainer } { const altVariant = variant('SV-1', { vehicle: 'sv1', driveType: 'fwd', region: 'emea' }) const neuVariant = variant('SV-1', { vehicle: 'sv1', driveType: 'fwd', region: 'emea' }) return { alt: emptyContainer({ activeVariants: [altVariant] }), neu: emptyContainer({ activeVariants: [neuVariant] }) } } it('is populated (never null) for a freshly-run compare, as a peer of materialDiff/profileDiff', () => { const { alt: altBase, neu: neuBase } = twoMatchedVariants() const alt: MultiQafContainer = { ...altBase, summaryAggregation: { perVariant: [ { variantId: 'SV-1', materialCosts: null, materialCostsByCurrency: [], manufacturingCosts: null, totalProductionCosts: null, toolingAndFixtureCost: null, setupCostAllocation: null, scrap: null, otherSurcharges: { value: 10, currency: 'EUR' }, offerBasePrice: null, offerBasePriceInclAllocation: null, offerPrice: null, }, ], formulaLineageNotes: [], }, } const neu: MultiQafContainer = { ...neuBase, summaryAggregation: { perVariant: [ { variantId: 'SV-1', materialCosts: null, materialCostsByCurrency: [], manufacturingCosts: null, totalProductionCosts: null, toolingAndFixtureCost: null, setupCostAllocation: null, scrap: null, otherSurcharges: { value: 14, currency: 'EUR' }, offerBasePrice: null, offerBasePriceInclAllocation: null, offerPrice: null, }, ], formulaLineageNotes: [], }, } const result = runMultiQafCompareFlow(alt, neu) expect(result.summaryTotalsDiff).not.toBeNull() const changed = result.summaryTotalsDiff!.findings.filter((f) => f.state === 'changed') expect(changed).toHaveLength(1) expect(changed[0]!.metricKey).toBe('otherSurcharges') expect(changed[0]!.deltaAbsolute).toBe(4) // No material/profile finding references SV-1 in this fixture (both // sides carry empty sharedMaterialMaster/profiles) — the changed // Summary metric has no explaining detail, so the additive // reviewRequired reason fires (module header "Step 7"). expect(result.reviewRequiredReasons).toContain('summary_totals_changed_without_material_or_profile_evidence') expect(result.reviewRequired).toBe(true) }) it('KAR-951 F7 fix: multiple changed summary metrics on the SAME variant still collapse to exactly one reviewRequiredReasons entry (memoized per-variant lookup stays correct, not just faster)', () => { // Regression proof for the F7 review-finding fix: `hasNoMaterialOrProfileEvidenceFor` // is now memoized per neuVariantId in a Map (both outcomes cached), replacing a // Set-based cache that only short-circuited the "no evidence" case. This fixture // gives ONE variant THREE independently-changed summary metrics (materialCosts, // otherSurcharges, offerBasePrice) — pre-fix this re-ran the full evidence scan 3x // for the identical variant; the memoized version must still produce the exact // same final result (one Set entry, one reason string, never duplicated/stale). const { alt: altBase, neu: neuBase } = twoMatchedVariants() const alt: MultiQafContainer = { ...altBase, summaryAggregation: { perVariant: [ { variantId: 'SV-1', materialCosts: { value: 100, currency: 'EUR' }, materialCostsByCurrency: [], manufacturingCosts: null, totalProductionCosts: null, toolingAndFixtureCost: null, setupCostAllocation: null, scrap: null, otherSurcharges: { value: 10, currency: 'EUR' }, offerBasePrice: { value: 500, currency: 'EUR' }, offerBasePriceInclAllocation: null, offerPrice: null, }, ], formulaLineageNotes: [], }, } const neu: MultiQafContainer = { ...neuBase, summaryAggregation: { perVariant: [ { variantId: 'SV-1', materialCosts: { value: 111, currency: 'EUR' }, materialCostsByCurrency: [], manufacturingCosts: null, totalProductionCosts: null, toolingAndFixtureCost: null, setupCostAllocation: null, scrap: null, otherSurcharges: { value: 14, currency: 'EUR' }, offerBasePrice: { value: 522, currency: 'EUR' }, offerBasePriceInclAllocation: null, offerPrice: null, }, ], formulaLineageNotes: [], }, } const result = runMultiQafCompareFlow(alt, neu) const changed = result.summaryTotalsDiff!.findings.filter((f) => f.state === 'changed') expect(changed.map((f) => f.metricKey).sort()).toEqual(['materialCosts', 'offerBasePrice', 'otherSurcharges']) expect(changed.every((f) => f.neuVariantId === 'SV-1')).toBe(true) // No material/profile finding references SV-1 in this fixture — all 3 // changed metrics on the same variant must collapse to exactly ONE // reviewRequiredReasons entry, never duplicated per changed metric. expect(result.reviewRequiredReasons.filter((r) => r === 'summary_totals_changed_without_material_or_profile_evidence')).toHaveLength(1) expect(result.reviewRequired).toBe(true) }) it('does NOT add the evidence-reason when a changed summary metric has no counterpart material/profile finding is FALSE (evidence present)', () => { // Reuses a real synthetic fixture pair that DOES produce material // findings for a matched variant, with summaryAggregation left empty // (default) — summaryTotalsDiff itself then has nothing to diff // (no perVariant data), so it can never contribute the evidence-reason // here; this is the natural "no data, no finding" case, distinct from // "data present, evidence present" (covered structurally by the // 'changed' finding requiring perVariant entries to exist at all). const alt = buildWideSlotFixture() const neu = deserializeMultiQafContainer(serializeMultiQafContainer(alt)) const result = runMultiQafCompareFlow(alt, neu) expect(result.reviewRequiredReasons).not.toContain('summary_totals_changed_without_material_or_profile_evidence') }) }) // ── (6) Round-trip persist -> reopen ──────────────────────────────────────── describe('serializeMultiQafComparisonResult / deserializeMultiQafComparisonResult', () => { it('round-trips a self-compare result byte-for-byte (deep equal) — the "reopen without re-parse" contract', () => { const alt = buildSharedManufacturingFixture() const neu = deserializeMultiQafContainer(serializeMultiQafContainer(alt)) const result = runMultiQafCompareFlow(alt, neu) const restored = deserializeMultiQafComparisonResult(serializeMultiQafComparisonResult(result)) expect(restored).toEqual(result) }) it('round-trips a cross-fixture result with overrides applied', () => { const alt = buildWideSlotFixture() const neu = buildMultiRowHeaderFixture() const result = runMultiQafCompareFlow(alt, neu) const restored = deserializeMultiQafComparisonResult(serializeMultiQafComparisonResult(result)) expect(restored).toEqual(result) }) it('rejects an envelope with an unsupported modelVersion (fail-closed, never silently reinterpreted)', () => { const badEnvelope = JSON.stringify({ modelVersion: 999, result: {} }) expect(() => deserializeMultiQafComparisonResult(badEnvelope)).toThrow(/modelVersion/) }) it('rejects an envelope missing the "result" key', () => { const badEnvelope = JSON.stringify({ modelVersion: MULTI_QAF_COMPARISON_RESULT_VERSION }) expect(() => deserializeMultiQafComparisonResult(badEnvelope)).toThrow(/result/) }) it('accepts a modelVersion:1 envelope (pre-KAR-944) and normalizes BOTH aggregateImpact and summaryTotalsDiff to null, never undefined (KAR-951)', () => { const v1Envelope = JSON.stringify({ modelVersion: 1, result: { modelVersion: 1, matchResult: [], droppedOverrides: [], containerDiff: {}, materialDiff: {}, profileDiff: {}, reconciliation: { alt: [], neu: [] }, reviewRequired: false, reviewRequiredReasons: [], // aggregateImpact/summaryTotalsDiff both absent — the exact shape a // pre-KAR-944 persisted record has. }, }) const restored = deserializeMultiQafComparisonResult(v1Envelope) expect(restored.aggregateImpact).toBeNull() expect(restored.summaryTotalsDiff).toBeNull() }) it('accepts a modelVersion:2 envelope (pre-KAR-951, post-KAR-944) and normalizes ONLY summaryTotalsDiff to null', () => { const v2Envelope = JSON.stringify({ modelVersion: 2, result: { modelVersion: 2, matchResult: [], droppedOverrides: [], containerDiff: {}, materialDiff: {}, profileDiff: {}, reconciliation: { alt: [], neu: [] }, reviewRequired: false, reviewRequiredReasons: [], aggregateImpact: null, // summaryTotalsDiff absent — the exact shape a modelVersion:2 record // persisted before KAR-951 has. }, }) const restored = deserializeMultiQafComparisonResult(v2Envelope) expect(restored.aggregateImpact).toBeNull() expect(restored.summaryTotalsDiff).toBeNull() }) }) // ── (7) multiQafBaselineStatusFor ─────────────────────────────────────────── describe('multiQafBaselineStatusFor', () => { it('maps reviewRequired:false to "ok" and reviewRequired:true to "baseline_review"', () => { expect( multiQafBaselineStatusFor({ modelVersion: MULTI_QAF_COMPARISON_RESULT_VERSION, matchResult: [], droppedOverrides: [], containerDiff: {} as never, materialDiff: {} as never, profileDiff: {} as never, reconciliation: { alt: [], neu: [] }, reviewRequired: false, reviewRequiredReasons: [], aggregateImpact: null, summaryTotalsDiff: null, }), ).toBe('ok') expect( multiQafBaselineStatusFor({ modelVersion: MULTI_QAF_COMPARISON_RESULT_VERSION, matchResult: [], droppedOverrides: [], containerDiff: {} as never, materialDiff: {} as never, profileDiff: {} as never, reconciliation: { alt: [], neu: [] }, reviewRequired: true, reviewRequiredReasons: ['match_overrides_dropped_on_drift'], aggregateImpact: null, summaryTotalsDiff: null, }), ).toBe('baseline_review') }) })