refactor(domain): encode comparison and lifecycle states exactly (#473)

* refactor(domain): encode comparison states exactly

* refactor(domain): make evidence lifecycles explicit

* refactor(browser): parse capture states once

* test: prefer behavior over implementation seams

* chore: refresh schema-derived metadata

* test(process): preserve lifecycle cleanup coverage

* test(hopper): bind rename cache coverage to dispatch
This commit is contained in:
morluto
2026-08-11 18:04:36 +08:00
committed by GitHub
parent e91c8c39c2
commit d65730c4c2
43 changed files with 1732 additions and 780 deletions
+171 -63
View File
@@ -36,6 +36,27 @@ interface ItemContext {
readonly maxCandidates: number;
}
type OneSidedNode =
| {
readonly left: ApplicationNode;
readonly right?: never;
readonly candidateRightNodeIds: readonly string[];
readonly candidateLeftNodeIds?: never;
}
| {
readonly left?: never;
readonly right: ApplicationNode;
readonly candidateRightNodeIds?: never;
readonly candidateLeftNodeIds: readonly string[];
};
type ComparisonItemSemantic<
Item extends
ApplicationVersionComparisonItem = ApplicationVersionComparisonItem,
> = Item extends ApplicationVersionComparisonItem
? Omit<Item, "item_id">
: never;
/** Classify matched, unmatched, and ambiguous nodes without inventing absence. */
export const classifyJavaScriptApplicationVersions = (
matching: ApplicationVersionMatchingProjection,
@@ -64,9 +85,10 @@ export const classifyJavaScriptApplicationVersions = (
candidates.length - context.maxCandidates,
);
return unmatchedItem(
node,
"left",
candidates.slice(0, context.maxCandidates),
{
left: node,
candidateRightNodeIds: candidates.slice(0, context.maxCandidates),
},
fullContext,
);
});
@@ -77,9 +99,10 @@ export const classifyJavaScriptApplicationVersions = (
candidates.length - context.maxCandidates,
);
return unmatchedItem(
node,
"right",
candidates.slice(0, context.maxCandidates),
{
right: node,
candidateLeftNodeIds: candidates.slice(0, context.maxCandidates),
},
fullContext,
);
});
@@ -112,18 +135,12 @@ const matchedItem = (
status === "unknown" && !dimensions.includes("coverage")
? [...dimensions, "coverage" as const]
: dimensions;
const semantic = {
const semantic: ComparisonItemSemantic = {
status,
node_kind: pair.left.kind,
left_node_id: pair.left.node_id,
right_node_id: pair.right.node_id,
match: {
status: "matched" as const,
basis: pair.basis,
confidence: pair.confidence,
candidate_left_node_ids: [],
candidate_right_node_ids: [],
},
match: matchedMatch(pair),
dimensions: finalDimensions,
evidence_links: itemEvidenceLinks(pair.left, pair.right, context),
limitations: pairLimitations(pair, status),
@@ -132,59 +149,150 @@ const matchedItem = (
};
const unmatchedItem = (
member: OneSidedNode,
context: ItemContext,
): ApplicationVersionComparisonItem =>
member.left === undefined
? rightOnlyItem(member.right, member.candidateLeftNodeIds, context)
: leftOnlyItem(member.left, member.candidateRightNodeIds, context);
const leftOnlyItem = (
node: ApplicationNode,
side: "left" | "right",
candidates: readonly string[],
candidateNodeIds: readonly string[],
context: ItemContext,
): ApplicationVersionComparisonItem => {
const ambiguous = candidates.length > 0;
const oppositeComplete =
(side === "left" ? context.rightGraph : context.leftGraph).coverage
.status === "complete";
const status: ApplicationVersionComparisonItem["status"] = ambiguous
? "unknown"
: oppositeComplete
? side === "left"
? "removed"
: "added"
: "unknown";
const semantic = {
status,
const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
const common = {
node_kind: node.kind,
left_node_id: side === "left" ? node.node_id : null,
right_node_id: side === "right" ? node.node_id : null,
match: {
status: ambiguous ? ("ambiguous" as const) : ("unmatched" as const),
basis: "none" as const,
confidence: "unknown" as const,
candidate_left_node_ids: side === "right" ? [...candidates] : [],
candidate_right_node_ids: side === "left" ? [...candidates] : [],
},
dimensions: [
"availability" as const,
...(status === "unknown" && !ambiguous ? (["coverage"] as const) : []),
],
evidence_links: itemEvidenceLinks(
side === "left" ? node : undefined,
side === "right" ? node : undefined,
context,
),
limitations: [
...(ambiguous
? [
"Multiple nodes share the same permitted match key; no cross-version pair was selected.",
]
: []),
...(status === "unknown" && !ambiguous
? [
"The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.",
]
: []),
],
evidence_links: itemEvidenceLinks(node, undefined, context),
};
return itemWithId(semantic);
if (firstCandidate !== undefined)
return itemWithId({
...common,
status: "unknown",
left_node_id: node.node_id,
right_node_id: null,
match: {
status: "ambiguous",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [],
candidate_right_node_ids: [firstCandidate, ...remainingCandidates],
},
dimensions: ["availability"],
limitations: [AMBIGUOUS_MATCH_LIMITATION],
});
const absenceObserved = context.rightGraph.coverage.status === "complete";
return itemWithId({
...common,
status: absenceObserved ? "removed" : "unknown",
left_node_id: node.node_id,
right_node_id: null,
match: unmatchedMatch(),
dimensions: absenceObserved
? ["availability"]
: ["availability", "coverage"],
limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
});
};
const rightOnlyItem = (
node: ApplicationNode,
candidateNodeIds: readonly string[],
context: ItemContext,
): ApplicationVersionComparisonItem => {
const [firstCandidate, ...remainingCandidates] = candidateNodeIds;
const common = {
node_kind: node.kind,
evidence_links: itemEvidenceLinks(undefined, node, context),
};
if (firstCandidate !== undefined)
return itemWithId({
...common,
status: "unknown",
left_node_id: null,
right_node_id: node.node_id,
match: {
status: "ambiguous",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [firstCandidate, ...remainingCandidates],
candidate_right_node_ids: [],
},
dimensions: ["availability"],
limitations: [AMBIGUOUS_MATCH_LIMITATION],
});
const absenceObserved = context.leftGraph.coverage.status === "complete";
return itemWithId({
...common,
status: absenceObserved ? "added" : "unknown",
left_node_id: null,
right_node_id: node.node_id,
match: unmatchedMatch(),
dimensions: absenceObserved
? ["availability"]
: ["availability", "coverage"],
limitations: absenceObserved ? [] : [INCOMPLETE_GRAPH_LIMITATION],
});
};
const matchedMatch = (
pair: ApplicationVersionNodePair,
): Extract<
ApplicationVersionComparisonItem["match"],
{ readonly status: "matched" }
> => {
const candidates: {
readonly candidate_left_node_ids: [];
readonly candidate_right_node_ids: [];
} = {
candidate_left_node_ids: [],
candidate_right_node_ids: [],
};
switch (pair.basis) {
case "exact-node-identity":
case "exact-content-digest":
case "exact-module-source-digest":
return {
status: "matched",
basis: pair.basis,
confidence: "exact",
...candidates,
};
case "source-map-identity":
return {
status: "matched",
basis: pair.basis,
confidence: "high",
...candidates,
};
case "structural-fingerprint":
case "semantic-key":
return {
status: "matched",
basis: pair.basis,
confidence: "medium",
...candidates,
};
}
};
const unmatchedMatch = (): Extract<
ApplicationVersionComparisonItem["match"],
{ readonly status: "unmatched" }
> => ({
status: "unmatched",
basis: "none",
confidence: "unknown",
candidate_left_node_ids: [],
candidate_right_node_ids: [],
});
const AMBIGUOUS_MATCH_LIMITATION =
"Multiple nodes share the same permitted match key; no cross-version pair was selected.";
const INCOMPLETE_GRAPH_LIMITATION =
"The opposite graph is incomplete, so an unmatched node cannot be classified as added or removed.";
const changedDimensions = (
pair: ApplicationVersionNodePair,
context: ItemContext,
@@ -340,9 +448,9 @@ const pairLimitations = (
: []),
];
const itemWithId = (
semantic: Omit<ApplicationVersionComparisonItem, "item_id">,
): ApplicationVersionComparisonItem => ({
const itemWithId = <Semantic extends ComparisonItemSemantic>(
semantic: Semantic,
): Semantic & { readonly item_id: string } => ({
...semantic,
item_id: `javc_item_${digestCanonical(semantic)}`,
});