@mortice/mapwright 0.8.0

package/dist/comparison/impact.js

@@ -0,0 +1,291 @@
+import { getRelationshipImpactPolicy, normalizeEndpointKind } from "./relationshipPolicy.js";
+export const IMPACT_DEFAULT_DEPTH = 3;
+export const IMPACT_MAX_DEPTH = 8;
+export const IMPACT_DEFAULT_LIMIT = 50;
+export const IMPACT_MAX_LIMIT = 200;
+export const IMPACT_MAX_VISITED_NODES = 10_000;
+export const IMPACT_MAX_TRAVERSED_EDGES = 50_000;
+export const IMPACT_MAX_PATHS_PER_ENDPOINT = 500;
+function emptySection(offset = 0, limit = IMPACT_DEFAULT_LIMIT) {
+    return { total: 0, returned: 0, offset, limit, truncated: false, records: [] };
+}
+function nodeKey(kind, id) {
+    return `${normalizeEndpointKind(kind)}:${id}`;
+}
+function edgeSortKey(edge) {
+    return `${edge.type}|${edge.fromKind}:${edge.fromId}|${edge.toKind}:${edge.toId}|${edge.provenance ?? ""}`;
+}
+/**
+ * Build adjacency for dependant-impact: from a dependency node, walk to dependants.
+ * For reverseTraversal relationships, an edge A→B (A imports B) yields adjacency B→A.
+ */
+function buildDependantAdjacency(edges) {
+    const adj = new Map();
+    for (const edge of edges) {
+        const policy = getRelationshipImpactPolicy(edge.type);
+        if (!policy.participatesInImpact)
+            continue;
+        const fromKind = normalizeEndpointKind(edge.fromKind);
+        const toKind = normalizeEndpointKind(edge.toKind);
+        const normalized = {
+            ...edge,
+            fromKind,
+            toKind
+        };
+        let dependantKey;
+        let dependencyKey;
+        if (policy.reverseTraversalForImpact) {
+            // dependency is "to"; dependant is "from" → walk from dependency toward dependant
+            dependencyKey = nodeKey(toKind, edge.toId);
+            dependantKey = nodeKey(fromKind, edge.fromId);
+        }
+        else {
+            dependencyKey = nodeKey(fromKind, edge.fromId);
+            dependantKey = nodeKey(toKind, edge.toId);
+        }
+        const list = adj.get(dependencyKey) ?? [];
+        list.push({
+            ...normalized,
+            // store traversal hop metadata: from=dependency side, to=dependant side for path clarity
+            fromKind: dependencyKey.split(":")[0],
+            fromId: dependencyKey.slice(dependencyKey.indexOf(":") + 1),
+            toKind: dependantKey.split(":")[0],
+            toId: dependantKey.slice(dependantKey.indexOf(":") + 1)
+        });
+        adj.set(dependencyKey, list);
+    }
+    for (const [key, list] of adj) {
+        adj.set(key, list.sort((a, b) => edgeSortKey(a).localeCompare(edgeSortKey(b))));
+    }
+    return adj;
+}
+function orderImpactRecords(records) {
+    const levelOrder = {
+        direct_evidence: 0,
+        transitive_inference: 1,
+        possible_impact: 2
+    };
+    return [...records].sort((a, b) => {
+        const l = levelOrder[a.evidenceLevel] - levelOrder[b.evidenceLevel];
+        if (l !== 0)
+            return l;
+        if (a.pathLength !== b.pathLength)
+            return a.pathLength - b.pathLength;
+        const p = (a.packageId ?? "").localeCompare(b.packageId ?? "");
+        if (p !== 0)
+            return p;
+        const k = a.kind.localeCompare(b.kind);
+        if (k !== 0)
+            return k;
+        const q = (a.qualifiedName ?? "").localeCompare(b.qualifiedName ?? "");
+        if (q !== 0)
+            return q;
+        return a.id.localeCompare(b.id);
+    });
+}
+function paginate(records, offset, limit, traversalIncomplete) {
+    const ordered = orderImpactRecords(records);
+    const slice = ordered.slice(offset, offset + limit);
+    return {
+        total: ordered.length,
+        returned: slice.length,
+        offset,
+        limit,
+        truncated: offset + slice.length < ordered.length || traversalIncomplete,
+        records: slice,
+        ...(traversalIncomplete ? { totalIsLowerBound: true, traversalIncomplete: true } : {})
+    };
+}
+function traverseDependants(startKind, startId, edges, snapshot, maxDepth) {
+    const adj = buildDependantAdjacency(edges);
+    const records = [];
+    const visited = new Set();
+    const warnings = [];
+    let traversedEdges = 0;
+    let incomplete = false;
+    const queue = [
+        { kind: normalizeEndpointKind(startKind), id: startId, depth: 0, path: [] }
+    ];
+    while (queue.length > 0) {
+        if (visited.size >= IMPACT_MAX_VISITED_NODES || traversedEdges >= IMPACT_MAX_TRAVERSED_EDGES) {
+            incomplete = true;
+            warnings.push("impact_work_budget_exhausted");
+            break;
+        }
+        if (records.length >= IMPACT_MAX_PATHS_PER_ENDPOINT) {
+            incomplete = true;
+            warnings.push("impact_max_paths_per_endpoint");
+            break;
+        }
+        const current = queue.shift();
+        const currentKey = nodeKey(current.kind, current.id);
+        if (current.depth > 0) {
+            if (visited.has(currentKey))
+                continue;
+            visited.add(currentKey);
+            const evidenceLevel = current.depth === 1 ? "direct_evidence" : "transitive_inference";
+            records.push({
+                id: current.id,
+                kind: current.kind,
+                pathLength: current.depth,
+                evidenceLevel,
+                path: current.path.map((e) => ({ ...e, snapshot }))
+            });
+        }
+        if (current.depth >= maxDepth)
+            continue;
+        const next = adj.get(currentKey) ?? [];
+        for (const edge of next) {
+            traversedEdges += 1;
+            if (traversedEdges > IMPACT_MAX_TRAVERSED_EDGES) {
+                incomplete = true;
+                warnings.push("impact_work_budget_exhausted");
+                break;
+            }
+            const hopKey = `${edge.type}|${edge.fromKind}:${edge.fromId}|${edge.toKind}:${edge.toId}`;
+            if (current.path.some((p) => `${p.relationshipType}|${p.fromKind}:${p.fromId}|${p.toKind}:${p.toId}` === hopKey)) {
+                continue;
+            }
+            const evidenceLevel = current.depth + 1 === 1 ? "direct_evidence" : "transitive_inference";
+            queue.push({
+                kind: edge.toKind,
+                id: edge.toId,
+                depth: current.depth + 1,
+                path: [
+                    ...current.path,
+                    {
+                        snapshot,
+                        relationshipType: edge.type,
+                        fromKind: edge.fromKind,
+                        fromId: edge.fromId,
+                        toKind: edge.toKind,
+                        toId: edge.toId,
+                        provenance: edge.provenance,
+                        evidenceLevel
+                    }
+                ]
+            });
+        }
+    }
+    return { records, incomplete, warnings };
+}
+function endpointForChange(change) {
+    const id = change.status === "added" ? change.headRecordId : change.baseRecordId;
+    if (!id)
+        return null;
+    const kindMap = {
+        packages: "package",
+        files: "file",
+        symbols: "symbol",
+        publicApis: "public-api",
+        tests: "test",
+        examples: "example",
+        capabilities: "capability",
+        relationships: "relationship",
+        diagnostics: "diagnostic"
+    };
+    return { kind: kindMap[change.domain] ?? change.domain, id };
+}
+function endpointsForCandidate(candidate) {
+    const kindMap = {
+        packages: "package",
+        files: "file",
+        symbols: "symbol",
+        publicApis: "public-api",
+        tests: "test",
+        examples: "example",
+        capabilities: "capability",
+        relationships: "relationship",
+        diagnostics: "diagnostic"
+    };
+    const kind = kindMap[candidate.domain] ?? candidate.domain;
+    return {
+        base: { kind, id: candidate.baseRecordId },
+        head: { kind, id: candidate.headRecordId }
+    };
+}
+export function getChangeImpact(comparison, changeId, options) {
+    const change = comparison.changes.find((c) => c.id === changeId);
+    const candidate = comparison.candidates.find((c) => c.id === changeId);
+    if (!change && !candidate)
+        return null;
+    const maxDepth = Math.min(Math.max(options?.maxDepth ?? IMPACT_DEFAULT_DEPTH, 1), IMPACT_MAX_DEPTH);
+    const limit = Math.min(Math.max(options?.limit ?? IMPACT_DEFAULT_LIMIT, 1), IMPACT_MAX_LIMIT);
+    const offset = Math.max(options?.offset ?? 0, 0);
+    let baseRaw = [];
+    let headRaw = [];
+    let incomplete = false;
+    if (candidate) {
+        const ends = endpointsForCandidate(candidate);
+        const baseT = traverseDependants(ends.base.kind, ends.base.id, comparison.graphIndex.base, "base", maxDepth);
+        const headT = traverseDependants(ends.head.kind, ends.head.id, comparison.graphIndex.head, "head", maxDepth);
+        baseRaw = baseT.records;
+        headRaw = headT.records;
+        incomplete = baseT.incomplete || headT.incomplete;
+    }
+    else if (change) {
+        if (change.domain === "relationships") {
+            // Relationship add/remove: affected path is the edge itself via endpoints
+            const edgeId = change.status === "added" ? change.headRecordId : change.baseRecordId;
+            const edges = change.status === "added" ? comparison.graphIndex.head : comparison.graphIndex.base;
+            const snap = change.status === "added" ? "head" : "base";
+            const match = edges.find((e) => e.id === edgeId);
+            if (match) {
+                const rec = {
+                    id: match.toId,
+                    kind: normalizeEndpointKind(match.toKind),
+                    pathLength: 1,
+                    evidenceLevel: "direct_evidence",
+                    path: [
+                        {
+                            snapshot: snap,
+                            relationshipType: match.type,
+                            fromKind: normalizeEndpointKind(match.fromKind),
+                            fromId: match.fromId,
+                            toKind: normalizeEndpointKind(match.toKind),
+                            toId: match.toId,
+                            provenance: match.provenance,
+                            evidenceLevel: "direct_evidence"
+                        }
+                    ]
+                };
+                if (change.status === "removed")
+                    baseRaw = [rec];
+                else
+                    headRaw = [rec];
+            }
+        }
+        else {
+            const endpoint = endpointForChange(change);
+            if (endpoint) {
+                if (change.status !== "added") {
+                    const t = traverseDependants(endpoint.kind, endpoint.id, comparison.graphIndex.base, "base", maxDepth);
+                    baseRaw = t.records;
+                    incomplete = incomplete || t.incomplete;
+                }
+                if (change.status !== "removed") {
+                    const headId = change.headRecordId ?? endpoint.id;
+                    const t = traverseDependants(endpoint.kind, headId, comparison.graphIndex.head, "head", maxDepth);
+                    headRaw = t.records;
+                    incomplete = incomplete || t.incomplete;
+                }
+            }
+        }
+    }
+    const baseImpact = paginate(baseRaw, offset, limit, incomplete);
+    const headImpact = paginate(headRaw, offset, limit, incomplete);
+    const baseIds = new Set(baseRaw.map((r) => `${r.kind}:${r.id}`));
+    const headIds = new Set(headRaw.map((r) => `${r.kind}:${r.id}`));
+    const retained = baseRaw.filter((r) => headIds.has(`${r.kind}:${r.id}`));
+    const removed = baseRaw.filter((r) => !headIds.has(`${r.kind}:${r.id}`));
+    const added = headRaw.filter((r) => !baseIds.has(`${r.kind}:${r.id}`));
+    return {
+        changeId,
+        baseImpact,
+        headImpact,
+        retainedImpact: paginate(retained, offset, limit, incomplete),
+        removedImpact: paginate(removed, offset, limit, incomplete),
+        addedImpact: paginate(added, offset, limit, incomplete),
+        possibleImpact: emptySection(offset, limit)
+    };
+}

package/dist/comparison/index.d.ts

@@ -0,0 +1,6 @@
+export { compareCatalogues } from "./compare.js";
+export { loadCataloguePair, validateCataloguePair } from "./validate.js";
+export { writeComparisonArtefact, loadComparisonArtefact } from "./store.js";
+export { getChangeImpact } from "./impact.js";
+export { comparisonIdentityId, changeIdentityId } from "./identity.js";
+export { DEFAULT_COMPARISON_OPTIONS, type ComparisonSnapshot, type ComparisonOptions, type ChangeRecord, type ComparisonError } from "./schema.js";

package/dist/comparison/index.js

@@ -0,0 +1,6 @@
+export { compareCatalogues } from "./compare.js";
+export { loadCataloguePair, validateCataloguePair } from "./validate.js";
+export { writeComparisonArtefact, loadComparisonArtefact } from "./store.js";
+export { getChangeImpact } from "./impact.js";
+export { comparisonIdentityId, changeIdentityId } from "./identity.js";
+export { DEFAULT_COMPARISON_OPTIONS } from "./schema.js";

package/dist/comparison/integrity.d.ts

@@ -0,0 +1,12 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import type { ComparisonError } from "./schema.js";
+export type IntegrityIssue = {
+    ref: string;
+    problem: string;
+    kind: "authoritative" | "derived";
+};
+/**
+ * Validate Schema 2 cross-references before comparison.
+ * Authoritative forward refs fail closed; derived backlinks may warn.
+ */
+export declare function validateReferentialIntegrity(snapshot: CatalogueSnapshot, side: "base" | "head"): ComparisonError | null;

package/dist/comparison/integrity.js

@@ -0,0 +1,199 @@
+import { normalizeEndpointKind } from "./relationshipPolicy.js";
+/**
+ * Validate Schema 2 cross-references before comparison.
+ * Authoritative forward refs fail closed; derived backlinks may warn.
+ */
+export function validateReferentialIntegrity(snapshot, side) {
+    const details = [];
+    const warnings = [];
+    const symbolIds = new Set(snapshot.symbols.map((s) => s.id));
+    const packageIds = new Set(snapshot.packages.map((p) => p.id));
+    const publicApiIds = new Set(snapshot.publicApis.map((p) => p.id));
+    const capabilityIds = new Set(snapshot.capabilities.map((c) => c.id));
+    const testIds = new Set(snapshot.tests.map((t) => t.id));
+    const exampleIds = new Set(snapshot.examples.map((e) => e.id));
+    const filePaths = new Set(snapshot.files.map((f) => f.path));
+    const auth = (ref, problem) => {
+        if (details.length < 50)
+            details.push({ ref, problem, kind: "authoritative" });
+    };
+    const derived = (ref, problem) => {
+        if (warnings.length < 50)
+            warnings.push({ ref, problem, kind: "derived" });
+    };
+    for (const api of snapshot.publicApis) {
+        if (api.symbolId && !symbolIds.has(api.symbolId)) {
+            auth(`publicApi:${api.id}.symbolId`, `missing symbol ${api.symbolId}`);
+        }
+        if (api.packageId && !packageIds.has(api.packageId)) {
+            auth(`publicApi:${api.id}.packageId`, `missing package ${api.packageId}`);
+        }
+        for (const cap of api.capabilityIds ?? []) {
+            if (!capabilityIds.has(cap))
+                auth(`publicApi:${api.id}.capabilityIds`, `missing capability ${cap}`);
+        }
+        for (const ex of api.examples ?? []) {
+            if (!exampleIds.has(ex))
+                auth(`publicApi:${api.id}.examples`, `missing example ${ex}`);
+        }
+        for (const test of api.tests ?? []) {
+            if (!testIds.has(test))
+                auth(`publicApi:${api.id}.tests`, `missing test ${test}`);
+        }
+    }
+    for (const symbol of snapshot.symbols) {
+        if (symbol.canonicalSymbolId && !symbolIds.has(symbol.canonicalSymbolId)) {
+            auth(`symbol:${symbol.id}.canonicalSymbolId`, `missing ${symbol.canonicalSymbolId}`);
+        }
+        if (symbol.duplicateOf && !symbolIds.has(symbol.duplicateOf)) {
+            auth(`symbol:${symbol.id}.duplicateOf`, `missing ${symbol.duplicateOf}`);
+        }
+        if (symbol.packageId && !packageIds.has(symbol.packageId)) {
+            auth(`symbol:${symbol.id}.packageId`, `missing package ${symbol.packageId}`);
+        }
+        for (const cap of symbol.capabilities ?? []) {
+            if (!capabilityIds.has(cap))
+                auth(`symbol:${symbol.id}.capabilities`, `missing capability ${cap}`);
+        }
+    }
+    for (const cap of snapshot.capabilities) {
+        for (const api of cap.publicApis ?? []) {
+            if (!publicApiIds.has(api))
+                auth(`capability:${cap.id}.publicApis`, `missing publicApi ${api}`);
+        }
+        for (const sym of cap.symbols ?? []) {
+            if (!symbolIds.has(sym))
+                auth(`capability:${cap.id}.symbols`, `missing symbol ${sym}`);
+        }
+        for (const pkg of cap.packages ?? []) {
+            if (!packageIds.has(pkg))
+                auth(`capability:${cap.id}.packages`, `missing package ${pkg}`);
+        }
+        for (const ex of cap.examples ?? []) {
+            if (!exampleIds.has(ex))
+                auth(`capability:${cap.id}.examples`, `missing example ${ex}`);
+        }
+        for (const test of cap.tests ?? []) {
+            if (!testIds.has(test))
+                auth(`capability:${cap.id}.tests`, `missing test ${test}`);
+        }
+        for (const file of cap.files ?? []) {
+            if (snapshot.files.length > 0 && !filePaths.has(file)) {
+                auth(`capability:${cap.id}.files`, `missing file ${file}`);
+            }
+        }
+    }
+    for (const test of snapshot.tests) {
+        if (test.symbolId && !symbolIds.has(test.symbolId)) {
+            auth(`test:${test.id}.symbolId`, `missing symbol ${test.symbolId}`);
+        }
+        for (const api of test.coversPublicApis ?? []) {
+            if (!publicApiIds.has(api))
+                auth(`test:${test.id}.coversPublicApis`, `missing publicApi ${api}`);
+        }
+        for (const cap of test.coversCapabilities ?? []) {
+            if (!capabilityIds.has(cap))
+                auth(`test:${test.id}.coversCapabilities`, `missing capability ${cap}`);
+        }
+        for (const sym of test.coversSymbols ?? []) {
+            if (!symbolIds.has(sym))
+                auth(`test:${test.id}.coversSymbols`, `missing symbol ${sym}`);
+        }
+    }
+    for (const example of snapshot.examples) {
+        for (const api of example.publicApiIds ?? []) {
+            if (!publicApiIds.has(api))
+                auth(`example:${example.id}.publicApiIds`, `missing publicApi ${api}`);
+        }
+        for (const cap of example.capabilityIds ?? []) {
+            if (!capabilityIds.has(cap))
+                auth(`example:${example.id}.capabilityIds`, `missing capability ${cap}`);
+        }
+        for (const sym of example.symbolIds ?? []) {
+            if (!symbolIds.has(sym))
+                auth(`example:${example.id}.symbolIds`, `missing symbol ${sym}`);
+        }
+    }
+    // Package membership arrays are treated as derived backlinks (may lag).
+    for (const pkg of snapshot.packages) {
+        for (const api of pkg.publicApis ?? []) {
+            if (!publicApiIds.has(api))
+                derived(`package:${pkg.id}.publicApis`, `missing publicApi ${api}`);
+        }
+        for (const test of pkg.tests ?? []) {
+            if (!testIds.has(test))
+                derived(`package:${pkg.id}.tests`, `missing test ${test}`);
+        }
+        for (const cap of pkg.capabilities ?? []) {
+            if (!capabilityIds.has(cap))
+                derived(`package:${pkg.id}.capabilities`, `missing capability ${cap}`);
+        }
+    }
+    for (const file of snapshot.files) {
+        for (const sym of file.symbols ?? []) {
+            if (!symbolIds.has(sym))
+                derived(`file:${file.path}.symbols`, `missing symbol ${sym}`);
+        }
+        for (const api of file.publicApis ?? []) {
+            if (!publicApiIds.has(api))
+                derived(`file:${file.path}.publicApis`, `missing publicApi ${api}`);
+        }
+        for (const cap of file.capabilities ?? []) {
+            if (!capabilityIds.has(cap))
+                derived(`file:${file.path}.capabilities`, `missing capability ${cap}`);
+        }
+    }
+    for (const rel of snapshot.relationships) {
+        for (const end of [rel.from, rel.to]) {
+            const kind = normalizeEndpointKind(end.kind);
+            if (kind === "external-package")
+                continue;
+            if (kind === "file")
+                continue;
+            if (kind === "symbol" && !symbolIds.has(end.id)) {
+                auth(`relationship:${rel.id}`, `missing symbol endpoint ${end.id}`);
+            }
+            else if (kind === "public-api" && !publicApiIds.has(end.id)) {
+                auth(`relationship:${rel.id}`, `missing publicApi endpoint ${end.id}`);
+            }
+            else if (kind === "package" && !packageIds.has(end.id)) {
+                auth(`relationship:${rel.id}`, `missing package endpoint ${end.id}`);
+            }
+            else if (kind === "capability" && !capabilityIds.has(end.id)) {
+                auth(`relationship:${rel.id}`, `missing capability endpoint ${end.id}`);
+            }
+            else if (kind === "test" && !testIds.has(end.id)) {
+                auth(`relationship:${rel.id}`, `missing test endpoint ${end.id}`);
+            }
+        }
+    }
+    for (const diag of snapshot.diagnostics) {
+        if (!diag.target)
+            continue;
+        const t = diag.target;
+        if (t.kind === "symbol" && !symbolIds.has(t.id))
+            auth(`diagnostic:${diag.id}`, `missing symbol ${t.id}`);
+        if ((t.kind === "publicApi" || t.kind === "public-api") && !publicApiIds.has(t.id)) {
+            auth(`diagnostic:${diag.id}`, `missing publicApi ${t.id}`);
+        }
+        if (t.kind === "package" && !packageIds.has(t.id))
+            auth(`diagnostic:${diag.id}`, `missing package ${t.id}`);
+        if (t.kind === "capability" && !capabilityIds.has(t.id)) {
+            auth(`diagnostic:${diag.id}`, `missing capability ${t.id}`);
+        }
+        if (t.kind === "test" && !testIds.has(t.id))
+            auth(`diagnostic:${diag.id}`, `missing test ${t.id}`);
+        if (t.kind === "file" && snapshot.files.length > 0 && !filePaths.has(t.id)) {
+            auth(`diagnostic:${diag.id}`, `missing file ${t.id}`);
+        }
+    }
+    if (details.length === 0) {
+        // Derived warnings alone do not fail comparison.
+        return null;
+    }
+    return {
+        code: "comparison_referential_integrity_failed",
+        message: `Referential integrity failed for ${side} catalogue (${details.length} authoritative issue(s)).`,
+        details: { side, issues: details, derivedWarnings: warnings.slice(0, 20) }
+    };
+}

package/dist/comparison/ordering.d.ts

@@ -0,0 +1,4 @@
+import type { ChangeRecord, CompatibilityFinding, CompatibilityClassification } from "./schema.js";
+export declare function orderChangeRecords(records: ChangeRecord[]): ChangeRecord[];
+export declare function orderCompatibilityFindings(findings: CompatibilityFinding[]): CompatibilityFinding[];
+export declare function aggregateCompatibility(findings: CompatibilityFinding[]): CompatibilityClassification | null;

package/dist/comparison/ordering.js

@@ -0,0 +1,69 @@
+const STATUS_ORDER = {
+    removed: 0,
+    modified: 1,
+    added: 2,
+    unchanged: 3
+};
+const SEVERITY_ORDER = {
+    breaking: 0,
+    potentially_breaking: 1,
+    unknown: 2,
+    non_breaking: 3,
+    documentation_only: 4,
+    not_applicable: 5
+};
+function cmp(a, b) {
+    const left = (a ?? "").normalize("NFC");
+    const right = (b ?? "").normalize("NFC");
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+export function orderChangeRecords(records) {
+    return [...records].sort((a, b) => {
+        const d = cmp(a.domain, b.domain);
+        if (d !== 0)
+            return d;
+        const s = (STATUS_ORDER[a.status] ?? 99) - (STATUS_ORDER[b.status] ?? 99);
+        if (s !== 0)
+            return s;
+        const p = cmp(a.packageId, b.packageId);
+        if (p !== 0)
+            return p;
+        const i = cmp(a.importPath ?? a.modulePath, b.importPath ?? b.modulePath);
+        if (i !== 0)
+            return i;
+        const q = cmp(a.qualifiedName ?? a.name, b.qualifiedName ?? b.name);
+        if (q !== 0)
+            return q;
+        return cmp(a.id, b.id);
+    });
+}
+export function orderCompatibilityFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const s = SEVERITY_ORDER[a.classification] - SEVERITY_ORDER[b.classification];
+        if (s !== 0)
+            return s;
+        const p = cmp(a.publicApiId, b.publicApiId);
+        if (p !== 0)
+            return p;
+        const r = cmp(a.ruleId, b.ruleId);
+        if (r !== 0)
+            return r;
+        return cmp(a.id, b.id);
+    });
+}
+export function aggregateCompatibility(findings) {
+    if (findings.length === 0) {
+        return null;
+    }
+    let best = "not_applicable";
+    for (const finding of findings) {
+        if (SEVERITY_ORDER[finding.classification] < SEVERITY_ORDER[best]) {
+            best = finding.classification;
+        }
+    }
+    return best;
+}

package/dist/comparison/projections.d.ts

@@ -0,0 +1,19 @@
+import type { CatalogueSnapshot } from "../catalogue/schema.js";
+import type { FacetDiff, RecordDomain } from "./schema.js";
+/** Strip line/column ranges from relationship evidence for semantic comparison. */
+export declare function semanticRelationshipEvidence(evidence: unknown): unknown;
+export declare function recordKey(domain: RecordDomain, record: Record<string, unknown>): string;
+export declare function indexDomain(domain: RecordDomain, snapshot: CatalogueSnapshot): Map<string, Record<string, unknown>>;
+/** Same-ID facet projection for a modified pair. Identity fields are not compared here. */
+export declare function projectFacets(domain: RecordDomain, base: Record<string, unknown>, head: Record<string, unknown>): FacetDiff[];
+export declare function normalizeConsoleScripts(value: unknown): Array<{
+    name: string;
+    target: string;
+}>;
+export declare function displayFields(domain: RecordDomain, record: Record<string, unknown>): {
+    packageId?: string | null;
+    importPath?: string | null;
+    modulePath?: string | null;
+    qualifiedName?: string | null;
+    name?: string | null;
+};