diff --git a/src/domain/bundleComparison.ts b/src/domain/bundleComparison.ts index a0fc4b1c5..ec9c73153 100644 --- a/src/domain/bundleComparison.ts +++ b/src/domain/bundleComparison.ts @@ -10,6 +10,7 @@ import { import type { ResidualUnknown } from "./residualUnknown.js"; import { digestSchema } from "./../domain/digests.js"; import { prefixedDigestSchema } from "./../domain/digests.js"; +import { comparisonStatusSchema } from "./comparisonStatus.js"; const evidenceIdSchema = prefixedDigestSchema("ev"); const classificationSchema = z.enum([ @@ -53,7 +54,7 @@ const bundleChangeSchema = z.object({ /** Deterministic classified delta between two canonical Evidence bundles. */ export const bundleComparisonResultSchema = z.object({ - status: z.enum(["unchanged", "changed", "unknown"]), + status: comparisonStatusSchema, left_bundle_sha256: digestSchema, right_bundle_sha256: digestSchema, summary: z.object({ diff --git a/src/domain/comparisonStatus.test.ts b/src/domain/comparisonStatus.test.ts new file mode 100644 index 000000000..a3b8b2e83 --- /dev/null +++ b/src/domain/comparisonStatus.test.ts @@ -0,0 +1,86 @@ +import { describe, expect, it } from "vitest"; + +import { + bundleClassificationToCanonical, + comparisonConclusionSchema, + comparisonStatusSchema, + functionStatusToCanonical, + scenarioArtifactStatusToCanonical, + sourceToBundleStatusToCanonical, +} from "./comparisonStatus.js"; + +describe("comparison status vocabulary", () => { + it("owns the canonical unchanged/changed/unknown triple", () => { + expect(comparisonStatusSchema.options).toEqual([ + "unchanged", + "changed", + "unknown", + ]); + expect(comparisonConclusionSchema.options).toEqual([ + "observed_change", + "derived_relationship", + "contradiction", + "unresolved_branch", + ]); + }); + + it("projects every bundle classification", () => { + expect( + ( + [ + "added", + "removed", + "changed", + "unknown", + "history_advanced", + "history_diverged", + ] as const + ).map(bundleClassificationToCanonical), + ).toEqual([ + "changed", + "changed", + "changed", + "unknown", + "changed", + "changed", + ]); + }); + + it("projects every source-to-bundle item status", () => { + expect( + ( + [ + "unchanged", + "modified", + "removed", + "split", + "merged", + "duplicated", + "unknown", + ] as const + ).map(sourceToBundleStatusToCanonical), + ).toEqual([ + "unchanged", + "changed", + "changed", + "changed", + "changed", + "changed", + "unknown", + ]); + }); + + it("projects every function dimension status without claiming truncated work", () => { + expect( + (["unchanged", "changed", "truncated", "unknown"] as const).map( + functionStatusToCanonical, + ), + ).toEqual(["unchanged", "changed", "unknown", "unknown"]); + }); + + it("projects every scenario artifact status", () => { + expect( + (["changed", "unknown"] as const).map(scenarioArtifactStatusToCanonical), + ).toEqual(["changed", "unknown"]); + }); +}); diff --git a/src/domain/comparisonStatus.ts b/src/domain/comparisonStatus.ts new file mode 100644 index 000000000..2674c24c8 --- /dev/null +++ b/src/domain/comparisonStatus.ts @@ -0,0 +1,70 @@ +import { z } from "zod"; + +/** + * Canonical top-level comparison outcome shared by every comparison + * pipeline. Pipeline-native detail enums (bundle classifications, + * source-to-bundle split/merge kinds, scenario alignment states, function + * truncation) keep their wire schemas; the mappers below project each of + * them onto this triple without changing any pipeline result. + */ +export const comparisonStatusSchema = z.enum([ + "unchanged", + "changed", + "unknown", +]); + +export type ComparisonStatus = z.infer; + +/** Canonical comparison conclusion shared by every comparison pipeline. */ +export const comparisonConclusionSchema = z.enum([ + "observed_change", + "derived_relationship", + "contradiction", + "unresolved_branch", +]); + +/** Project a bundle change classification onto the canonical triple. */ +export const bundleClassificationToCanonical = ( + classification: + | "added" + | "removed" + | "changed" + | "unknown" + | "history_advanced" + | "history_diverged", +): ComparisonStatus => (classification === "unknown" ? "unknown" : "changed"); + +/** Project a source-to-bundle item status onto the canonical triple. */ +export const sourceToBundleStatusToCanonical = ( + status: + | "unchanged" + | "modified" + | "removed" + | "split" + | "merged" + | "duplicated" + | "unknown", +): ComparisonStatus => + status === "unchanged" + ? "unchanged" + : status === "unknown" + ? "unknown" + : "changed"; + +/** + * Project a function dimension status onto the canonical triple. A + * truncated dimension cannot support an unchanged/changed claim. + */ +export const functionStatusToCanonical = ( + status: "unchanged" | "changed" | "truncated" | "unknown", +): ComparisonStatus => + status === "unchanged" + ? "unchanged" + : status === "changed" + ? "changed" + : "unknown"; + +/** Project a browser-scenario artifact status onto the canonical triple. */ +export const scenarioArtifactStatusToCanonical = ( + status: "changed" | "unknown", +): ComparisonStatus => status; diff --git a/src/domain/functionComparisonNormalization.ts b/src/domain/functionComparisonNormalization.ts index 50fdb24b0..43871b123 100644 --- a/src/domain/functionComparisonNormalization.ts +++ b/src/domain/functionComparisonNormalization.ts @@ -1,5 +1,4 @@ -import canonicalize from "canonicalize"; - +import { canonicalJson } from "./comparisonSemantics.js"; import { compareCodePoints } from "./canonicalOrdering.js"; import type { @@ -179,8 +178,8 @@ export const stringAndNameProjection = ( export const sorted = (values: readonly unknown[]): readonly unknown[] => [...values].sort((left, right) => { - const leftJson = canonicalJson(left); - const rightJson = canonicalJson(right); + const leftJson = canonicalJson(left, "Function normalization"); + const rightJson = canonicalJson(right, "Function normalization"); // Preserve existing collation while ordering distinct values within a tie. return ( leftJson.localeCompare(rightJson) || @@ -218,10 +217,3 @@ const relativeAddress = (value: string, base: string): string | null => { ? null : String(parsed - parsedBase); }; - -const canonicalJson = (value: unknown): string => { - const encoded = canonicalize(value); - if (encoded === undefined) - throw new TypeError("Function normalization could not canonicalize data"); - return encoded; -};