fix(javascript): report version-comparison coverage unknown when a source graph cannot tell (#11206)

* fix(javascript): report version-comparison coverage unknown when a source graph cannot tell

* refactor(javascript): name the unavailable-graph coverage mapping once

* fix(javascript): give the version change graph and its edges the same unknown coverage

* fix(javascript): report export-shape comparison coverage unknown when a source graph cannot tell (#11218)

* fix(javascript): report export-shape comparison coverage unknown when a source graph cannot tell

* test(javascript): keep unknown export-shape coverage beside a truncated projection

* fix(javascript): read runtime-reconciliation input coverage once and report unknown when a static graph cannot tell (#11230)

* fix(javascript): read runtime-reconciliation input coverage once and report unknown when a static graph cannot tell

* fix(javascript): keep a known input truncation beside unknown reconciliation coverage

* fix(javascript): report export-shape source omission counts unknown when a side has no projection (#11261)

compare_export_shapes reported left/right_omitted_fields and omitted_property_coverage as 0 for a side whose export selection recovered no return-shape projection (missing, ambiguous or unavailable), while the sibling source_omitted_variants already reported null. Add Known<T> (src/domain/known.ts) and read each side's source coverage once through it; the counts are now null (unknown) with a limitation naming why. The runtime-reconciliation graph's omission sum and its parallel 'omissions known' flag become one Known<number> via sumKnownCounts (no output change).
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 23:59:23 +08:00
1 parent 8b7829e385
commit 90ce8bae4a
15 files changed
+665 -169

No files matched your search

@@ -2,10 +2,14 @@ import { uniqueSorted } from "../canonicalOrdering.js";
import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
import { canonicalJson } from "../comparisonSemantics.js";
import { digestCanonicalValue } from "../canonicalDigest.js";
import { joinCoverageStatus } from "../coverage.js";
import { known, knownOrNull, unknownBecause, type Known } from "../known.js";
import { applicationCoverageKnowledge } from "./javascriptApplicationEvidenceSchemas.js";
import {
javaScriptExportShapeComparisonResultSchema,
type JavaScriptExportShapeComparisonChange,
type JavaScriptExportShapeComparisonResult,
type ProjectedExportReturnShapes,
} from "./javascriptExportShapeComparisonSchemas.js";
import {
retainJavaScriptExportShapes,
@@ -125,20 +129,42 @@ interface CoverageInput {
readonly omittedChanges: number;
}
type ReturnShapeCoverage = ProjectedExportReturnShapes["return_shape_coverage"];
/**
* The side's source return-shape coverage. A side without a projection did
* not recover return shapes, so its source omissions are unknown, not zero.
*/
const sourceCoverage = (
selection: SelectedJavaScriptExport,
): Known<ReturnShapeCoverage> =>
selection.projection === null
? unknownBecause(`the export selection is ${selection.selection.status}`)
: known(selection.projection.return_shape_coverage);
const comparisonCoverage = (context: CoverageInput) => {
const leftSource = context.left.projection?.return_shape_coverage;
const rightSource = context.right.projection?.return_shape_coverage;
const leftSource = sourceCoverage(context.left);
const rightSource = sourceCoverage(context.right);
const omittedCandidates =
context.left.selection.omitted_candidates +
context.right.selection.omitted_candidates;
const truncated = comparisonTruncated(context, omittedCandidates);
const partial = comparisonPartial(context);
// A source graph that cannot tell its coverage makes the comparison
// unknown, even beside a known gap.
const graphs = joinCoverageStatus([
applicationCoverageKnowledge(context.input.left.graph.coverage.status),
applicationCoverageKnowledge(context.input.right.graph.coverage.status),
]);
return {
status: truncated
? ("truncated" as const)
: partial
? ("partial" as const)
: ("complete-within-inputs" as const),
status:
graphs === "unknown"
? ("unknown" as const)
: truncated
? ("truncated" as const)
: partial
? ("partial" as const)
: ("complete-within-inputs" as const),
left_graph_status: context.input.left.graph.coverage.status,
right_graph_status: context.input.right.graph.coverage.status,
paired_variants: context.pairing.pairs.length,
@@ -146,13 +172,32 @@ const comparisonCoverage = (context: CoverageInput) => {
unpaired_right_variants: context.pairing.unpairedRight.length,
omitted_left_variants: context.leftRetained.omitted,
omitted_right_variants: context.rightRetained.omitted,
left_source_omitted_variants: leftSource?.omitted_return_sites ?? null,
right_source_omitted_variants: rightSource?.omitted_return_sites ?? null,
left_omitted_fields: leftSource?.omitted_fields ?? 0,
right_omitted_fields: rightSource?.omitted_fields ?? 0,
left_omitted_property_coverage: leftSource?.omitted_property_coverage ?? 0,
right_omitted_property_coverage:
rightSource?.omitted_property_coverage ?? 0,
// omitted_return_sites is itself null when the projection could not
// count them.
left_source_omitted_variants: knownOrNull(
leftSource,
({ omitted_return_sites }) => omitted_return_sites,
),
right_source_omitted_variants: knownOrNull(
rightSource,
({ omitted_return_sites }) => omitted_return_sites,
),
left_omitted_fields: knownOrNull(
leftSource,
({ omitted_fields }) => omitted_fields,
),
right_omitted_fields: knownOrNull(
rightSource,
({ omitted_fields }) => omitted_fields,
),
left_omitted_property_coverage: knownOrNull(
leftSource,
({ omitted_property_coverage }) => omitted_property_coverage,
),
right_omitted_property_coverage: knownOrNull(
rightSource,
({ omitted_property_coverage }) => omitted_property_coverage,
),
omitted_candidates: omittedCandidates,
omitted_changes: context.omittedChanges,
};
@@ -172,8 +217,9 @@ const comparisonTruncated = (
const sourceProjectionTruncated = (
selection: SelectedJavaScriptExport,
): boolean => {
const coverage = selection.projection?.return_shape_coverage;
if (coverage === undefined) return false;
const source = sourceCoverage(selection);
if (!source.known) return false;
const coverage = source.value;
return (
coverage.status === "truncated" ||
coverage.omitted_fields > 0 ||
@@ -194,19 +240,38 @@ const comparisonPartial = (context: CoverageInput): boolean =>
context.allChanges.some(({ status }) => status === "unknown");
const selectionPartial = (selection: SelectedJavaScriptExport): boolean => {
const coverage = selection.projection?.return_shape_coverage;
const source = sourceCoverage(selection);
return (
selection.selection.status !== "selected" ||
!selection.observationComplete ||
coverage?.status !== "complete" ||
coverage.projection_complete !== true
!source.known ||
source.value.status !== "complete" ||
!source.value.projection_complete
);
};
/** Name each side whose source omission counts are null, and why. */
const unknownSourceLimitations = (
left: SelectedJavaScriptExport,
right: SelectedJavaScriptExport,
): string[] =>
(
[
["left", sourceCoverage(left)],
["right", sourceCoverage(right)],
] as const
).flatMap(([side, source]) =>
source.known
? []
: [
`The ${side} export has no return-shape projection because ${source.reason}, so its source omission counts are null (unknown), not zero.`,
],
);
const comparisonLimitations = (
left: SelectedJavaScriptExport,
right: SelectedJavaScriptExport,
status: "complete-within-inputs" | "partial" | "truncated",
status: JavaScriptExportShapeComparisonResult["coverage"]["status"],
): string[] =>
uniqueSorted([
"Return shapes are inferred from inert syntax and do not prove runtime behavior.",
@@ -215,6 +280,7 @@ const comparisonLimitations = (
"This static comparison cannot establish runtime semantics; run behavioral probes directly against the relevant application versions when that evidence is required.",
...left.limitations,
...right.limitations,
...unknownSourceLimitations(left, right),
...(status === "truncated"
? [
"Comparison output or source return-shape recovery reached an explicit limit.",
@@ -225,6 +291,11 @@ const comparisonLimitations = (
"At least one selector, graph, return shape, or property boundary is incomplete.",
]
: []),
...(status === "unknown"
? [
"At least one source graph's coverage is unknown or unavailable, so the comparison's coverage is unknown.",
]
: []),
]);
const summarize = (