differential.ts

// Copyright 2026 MedDeck LTDA. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Shared machinery of the differential suites, which replay the corpora in
// fixtures/data/differential_*.json (generated by fixtures/gen/differential*.go from
// the real Go code) and require the port to reach Go's verdict on every record.
// See docs/compatibility.md ("Differential tests") and
// docs/decisions/0215-differential-corpora.md.
//
// A record may differ from Go only under a named entry of DIVERGENCES, each of which
// cites the ADR that decided it and states the exact behaviour the port must show
// instead. A suite that meets a difference no entry covers reports it as a mismatch;
// a suite that applies an entry counts it, so the report shows how often each
// documented divergence occurs and a divergence cannot spread silently.

import { expect } from "vitest";
import { maxQuotedNum } from "../../internal/gostd/strconv.ts";

/** A DivergenceRule is one documented, ADR-backed way the port may differ from Go. */
export interface DivergenceRule {
	/** adrs are the decision records (docs/decisions/NNNN-*.md) that decided it. */
	readonly adrs: readonly string[];
	/** rule says what the port does instead of what Go does, precisely enough to assert. */
	readonly rule: string;
}

/**
 * DIVERGENCES is the allow-list. Adding an entry needs an ADR; the suites assert the
 * behaviour each entry states, not merely that "something differs".
 * docs/decisions/0216-differential-divergence-allow-list.md explains each entry.
 */
export const DIVERGENCES = {
	"invalid-utf8-text": {
		adrs: ["0203", "0216"],
		rule:
			"For an input that is not valid UTF-8, text the port quotes from it in an error message spells " +
			"each invalid sequence as U+FFFD, where Go's %q spells each invalid byte as \\xNN. The verdict and " +
			"the rest of the message are Go's.",
	},
	"checkpoint-origin-utf8": {
		adrs: ["0203"],
		rule:
			"Checkpoint.unmarshal rejects a checkpoint whose origin line is not valid UTF-8 with " +
			'"invalid checkpoint - origin is not valid UTF-8", which Go accepts.',
	},
	"checkpoint-root-hash-size": {
		adrs: ["0202"],
		rule:
			"parseCheckpoint rejects a signed checkpoint whose root hash is not 32 bytes with " +
			'"failed to unmarshal checkpoint: invalid checkpoint - root hash has unexpected size N, want 32", ' +
			"after upstream's signature, unmarshal and origin checks and carrying the note; Go accepts it.",
	},
	"ed25519-unsafe-verifier-key": {
		adrs: ["0206", "0174"],
		rule:
			"newVerifier and newVerifierForCosignatureV1 refuse an Ed25519 public key that is a small-order point (errVerifierSmallOrderKey) " +
			"or a non-canonical encoding of a point (errVerifierNonCanonicalKey), which Go's constructors " +
			"accept. verifyEd25519 itself returns Go's verdict for every key.",
	},
	"merkle-hash-size": {
		adrs: ["0202"],
		rule:
			"verifyInclusion/rootFromInclusionProof/verifyConsistency throw " +
			'"<proof[i]|root|root1|root2> has unexpected size N, want 32" for a proof hash or root that is not ' +
			"32 bytes, only where Go succeeds: after every check upstream makes, its root comparisons included. " +
			"Go treats such a hash as opaque bytes; where Go rejects, the port returns Go's error, a " +
			"RootMismatchError with Go's calculated root included.",
	},
	"witness-quorum-hardening": {
		adrs: ["0184"],
		rule:
			"newWitnessGroupFromPolicy rejects a group that names a child twice, two witnesses with the same " +
			'verifier key, and an explicit threshold of 0, with "repeated component %q in group definition", ' +
			'"witness %q has the same verifier key as witness %q" and "invalid threshold "0" for group %q: ' +
			'must be at least 1". Go processes every earlier line as the port does: it accepts the line, or, for a ' +
			"group line, may fail later on that same line on a child the port never reaches (the threshold is " +
			"checked before the children), or fails on a later line, or only after the last.",
	},
	"witness-url-https": {
		adrs: ["0185", "0241"],
		rule:
			"newWitnessGroupFromPolicy rejects a witness URL, which Go accepts, whose endpoint (as Go's url.Parse, " +
			"JoinPath and String make it) does not use https, or http to a loopback host, relative references " +
			'included, with "invalid witness config %q: witness URL %q must use https (http is accepted only for ' +
			'a loopback host)". Go processes every line up to and including it as the port does, and fails, if at ' +
			"all, on a later line or after the last.",
	},
	"witness-url-fetchable": {
		adrs: ["0241"],
		rule:
			"newWitnessGroupFromPolicy rejects an https or http witness URL, which Go accepts, whose endpoint has no " +
			'host in Go\'s reading, with "invalid witness config %q: witness URL %q has no host", or that the ' +
			'platform URL parser rejects, with "invalid witness config %q: witness URL %q is rejected by the ' +
			'platform URL parser, which fetch uses". Go processes every line up to and including it as the port ' +
			"does, and fails, if at all, on a later line or after the last.",
	},
	"witness-policy-utf8": {
		adrs: ["0242"],
		rule:
			"newWitnessGroupFromPolicy rejects a policy line whose text before its first '#' is not valid UTF-8, " +
			'when it reaches that line, with "witness policy line is not valid UTF-8"; Go reads the bytes. Lines ' +
			"before it get Go's verdict (Go fails, if at all, on that line or later), and invalid bytes in a " +
			"comment are accepted, as in Go.",
	},
	"numerror-quote-bound": {
		adrs: ["0204"],
		rule:
			'A strconv NumError message quotes at most 64 code points of the input and then appends "..."; Go ' +
			"quotes the whole input. The quoted prefix and the rest of the message are Go's.",
	},
	"entry-size-limit": {
		adrs: ["0182"],
		rule:
			"newEntry throws for data longer than 65535 bytes, which Go accepts and then writes with a truncated " +
			"uint16 length prefix.",
	},
	"tile-bundle-size-limit": {
		adrs: ["0194"],
		rule:
			'HashTile.unmarshalText rejects more than 256 hashes ("tile of N hashes exceeds the maximum of 256") ' +
			'and EntryBundle.unmarshalText stops at a 257th entry ("entry bundle holds more than the maximum of ' +
			'256 entries"); Go parses any number. Applied to a tile Go parses with more than 256 hashes, and to a ' +
			"bundle Go parses with more than 256 entries or rejects: the port parsed 256 entries as Go did before " +
			"stopping, so Go's error is on an entry after them. A smaller malformed input gets Go's error.",
	},
	"uint-count-overflow": {
		adrs: ["0014"],
		rule:
			"layout.range throws a RangeError where the count N of a single bundle wraps around Go's uint " +
			"(a request whose end overflows 2^64), instead of yielding the wrapped count.",
	},
} as const satisfies Record<string, DivergenceRule>;

/** DivergenceName names an entry of {@link DIVERGENCES}. */
export type DivergenceName = keyof typeof DIVERGENCES;

/** maxReported is how many mismatches a failing report spells out. */
const maxReported = 25;

/**
 * DifferentialReport collects the outcome of replaying one corpus: how many records were
 * checked, every mismatch (the first few spelled out in full, with the input), and how
 * often each documented divergence was applied.
 */
export class DifferentialReport {
	readonly corpus: string;
	checked = 0;
	mismatchCount = 0;
	readonly mismatches: string[] = [];
	readonly divergences = new Map<DivergenceName, number>();

	constructor(corpus: string) {
		this.corpus = corpus;
	}

	/** record counts one replayed record. */
	record(): void {
		this.checked++;
	}

	/** fail records a mismatch for the record identified by id. */
	fail(id: string, message: string): void {
		this.mismatchCount++;
		if (this.mismatches.length < maxReported) {
			this.mismatches.push(`${id}: ${message}`);
		}
	}

	/**
	 * equal compares one field of a record. Values are compared by their canonical JSON
	 * rendering, with bigints as decimal strings and Uint8Arrays as hex, so that Go's
	 * fixture spelling and the port's values compare directly. Returns whether they match.
	 */
	equal(id: string, field: string, go: unknown, ts: unknown): boolean {
		const g = canonical(go);
		const t = canonical(ts);
		if (g !== t) {
			this.fail(id, `${field}: go=${clip(g)} ts=${clip(t)}`);
			return false;
		}
		return true;
	}

	/** diverge records that the documented divergence name was applied to record id. */
	diverge(name: DivergenceName): void {
		this.divergences.set(name, (this.divergences.get(name) ?? 0) + 1);
	}

	/**
	 * assertClean fails the test unless every record matched Go or a documented divergence,
	 * at least minChecked records were replayed (so a corpus that failed to load cannot
	 * pass vacuously), only the divergences listed in allowed were applied, and each one
	 * listed in required was applied at least once (so the corpus keeps exercising it).
	 */
	assertClean(
		minChecked: number,
		allowed: readonly DivergenceName[] = [],
		required: readonly DivergenceName[] = [],
	): void {
		for (const name of this.divergences.keys()) {
			if (!allowed.includes(name)) {
				this.fail("(report)", `divergence ${name} applied, but this corpus does not allow it`);
			}
		}
		for (const name of required) {
			if ((this.divergences.get(name) ?? 0) === 0) {
				this.fail("(report)", `divergence ${name} was never applied; the corpus no longer exercises it`);
			}
		}
		const summary = this.summary();
		expect(this.checked, `${this.corpus}: too few records replayed\n${summary}`).toBeGreaterThanOrEqual(minChecked);
		expect(this.mismatchCount, summary).toBe(0);
	}

	/** summary renders the report for a failure message. */
	summary(): string {
		const div = [...this.divergences].map(([k, v]) => `${k}=${v}`).join(", ") || "none";
		const lines = [
			`${this.corpus}: ${this.checked} records, ${this.mismatchCount} mismatches, divergences: ${div}`,
			...this.mismatches,
		];
		if (this.mismatchCount > this.mismatches.length) {
			lines.push(`... and ${this.mismatchCount - this.mismatches.length} more`);
		}
		return lines.join("\n");
	}
}

/** Outcome is the result of calling a function that may throw. */
export type Outcome<T> = { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: unknown };

/** attempt runs f and captures its result or the value it threw. */
export function attempt<T>(f: () => T): Outcome<T> {
	try {
		return { ok: true, value: f() };
	} catch (error) {
		return { ok: false, error };
	}
}

/** attemptAsync is {@link attempt} for an async function. */
export async function attemptAsync<T>(f: () => Promise<T>): Promise<Outcome<T>> {
	try {
		return { ok: true, value: await f() };
	} catch (error) {
		return { ok: false, error };
	}
}

/** messageOf renders a thrown value the way Go's err.Error() reads. */
export function messageOf(e: unknown): string {
	return e instanceof Error ? e.message : String(e);
}

/**
 * sameModuloInvalidUTF8 reports whether a Go error text and the port's agree once every
 * run of invalid-byte spellings is collapsed: Go's `\xNN` escapes and a literal U+FFFD on
 * one side; on the other, the literal U+FFFD the port writes for each invalid sequence,
 * and the `\ufffd` escape it writes only for a lone surrogate. This is the comparison the
 * "invalid-utf8-text" divergence permits.
 */
export function sameModuloInvalidUTF8(go: string, ts: string): boolean {
	const g = go.replace(/(?:\\x[89a-f][0-9a-f]|\ufffd)+/g, "\u0000");
	const t = ts.replace(/(?:\\ufffd|\ufffd)+/g, "\u0000");
	return g === t;
}

/**
 * sameModuloQuoteBound reports whether the port's error text is Go's with one quoted
 * strconv input cut at 64 code points and marked "...", the "numerror-quote-bound"
 * divergence: ts must read `<before>parsing "<prefix>"...<after>` where Go reads
 * `<before>parsing "<prefix><more>"<after>`, and `<prefix>` must quote exactly
 * maxQuotedNum (64) code points of the input.
 */
export function sameModuloQuoteBound(go: string, ts: string): boolean {
	const m = /^(.*parsing )("(?:[^"\\]|\\.)*")\.\.\.(.*)$/s.exec(ts);
	if (m === null) {
		return false;
	}
	const [, before, quoted, after] = m as unknown as [string, string, string, string];
	const prefix = quoted.slice(0, -1);
	return (
		quotedCodePoints(prefix.slice(1)) === maxQuotedNum &&
		go.startsWith(before + prefix) &&
		go.endsWith(`"${after}`) &&
		go.length > before.length + quoted.length + after.length
	);
}

/**
 * quotedCodePoints counts the code points the body of a Go double-quoted string literal
 * spells: each escape (`\n`, `\"`, `\xNN`, `\uNNNN`, `\UNNNNNNNN`, ...) is one, as is
 * each other character.
 */
function quotedCodePoints(body: string): number {
	const escapeWidth: Readonly<Record<string, number>> = { x: 4, u: 6, U: 10 };
	let n = 0;
	for (let i = 0; i < body.length; n++) {
		if (body[i] === "\\") {
			i += escapeWidth[body[i + 1] ?? ""] ?? 2;
		} else {
			i += (body.codePointAt(i) ?? 0) > 0xffff ? 2 : 1;
		}
	}
	return n;
}

const hexDigits = "0123456789abcdef";

function toHexString(b: Uint8Array): string {
	let out = "";
	for (const v of b) {
		out += hexDigits[v >> 4];
		out += hexDigits[v & 0x0f];
	}
	return out;
}

/** canonical renders a value for comparison: bigint as decimal, bytes as hex. */
export function canonical(v: unknown): string {
	return (
		JSON.stringify(v, (_k, x: unknown) => {
			if (typeof x === "bigint") {
				return x.toString();
			}
			if (x instanceof Uint8Array) {
				return toHexString(x);
			}
			return x;
		}) ?? "undefined"
	);
}

function clip(s: string): string {
	return s.length > 300 ? `${s.slice(0, 300)}…` : s;
}