mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +00:00
Admit exact string heap aliases and retain independent Module row facts for distinct declarations. Bind the optional partial row to the same scope checks as named Module Evidence.
298 lines
12 KiB
TypeScript
298 lines
12 KiB
TypeScript
import { managedModuleRow } from "./managedModuleIdentity.js";
|
|
import { joinCoverageStatus, type CoverageStatus } from "../coverage.js";
|
|
import type {
|
|
ManagedMemberComparisonResult,
|
|
ManagedMemberComparisonSide,
|
|
} from "./managedMemberComparison.js";
|
|
import {
|
|
managedInspectionCoverage,
|
|
type ManagedMemberInspection,
|
|
} from "./managedArtifact.js";
|
|
|
|
interface ComparisonCoverageInput {
|
|
readonly left: ManagedMemberInspection;
|
|
readonly right: ManagedMemberInspection;
|
|
readonly selectionAgreement: SelectionAgreement;
|
|
}
|
|
|
|
type SelectionAgreement = "same" | "different" | "unknown";
|
|
|
|
export const buildComparisonCoverage = ({
|
|
left,
|
|
right,
|
|
selectionAgreement,
|
|
}: ComparisonCoverageInput): ManagedMemberComparisonResult["coverage"] => {
|
|
// An unavailable side examined nothing, and an unknown selection agreement
|
|
// cannot tell whether both sides cover the same types: either makes the
|
|
// comparison unknown, even beside a known gap.
|
|
const joined = joinCoverageStatus([
|
|
managedInspectionCoverage(left.coverage.state),
|
|
managedInspectionCoverage(right.coverage.state),
|
|
selectionAgreement === "unknown"
|
|
? "unknown"
|
|
: selectionAgreement === "different" || !sameMethodRows(left, right)
|
|
? "partial"
|
|
: "complete",
|
|
]);
|
|
return {
|
|
status: joined === "complete" ? "complete-within-inputs" : joined,
|
|
left_status: left.coverage.state,
|
|
right_status: right.coverage.state,
|
|
};
|
|
};
|
|
|
|
/** Full MethodDef coverage is required before inferring cross-build absence. */
|
|
export const hasCompleteMethodRows = (
|
|
result: ManagedMemberInspection,
|
|
): boolean =>
|
|
result.method_rows !== null &&
|
|
result.method_rows.offset === 0 &&
|
|
result.method_rows.count === result.method_rows.total;
|
|
|
|
const sameMethodRows = (
|
|
left: ManagedMemberInspection,
|
|
right: ManagedMemberInspection,
|
|
): boolean =>
|
|
(hasCompleteMethodRows(left) && hasCompleteMethodRows(right)) ||
|
|
(left.method_rows !== null &&
|
|
right.method_rows !== null &&
|
|
left.method_rows.offset === right.method_rows.offset &&
|
|
left.method_rows.count === right.method_rows.count &&
|
|
left.method_rows.total === right.method_rows.total);
|
|
|
|
/** One side's build-local TypeDef lookup and observed nominal selection. */
|
|
const declaringTypeScope = (result: ManagedMemberInspection) => {
|
|
const names = new Map(
|
|
result.types.map((type) => [type.token, type.name_sha256]),
|
|
);
|
|
return {
|
|
names,
|
|
selected:
|
|
result.selection === null
|
|
? null
|
|
: new Set([...names.values()].filter((name) => name !== null)),
|
|
complete:
|
|
result.coverage.state === "complete" &&
|
|
result.metadata.status === "complete" &&
|
|
result.types.every(({ name_sha256 }) => name_sha256 !== null),
|
|
};
|
|
};
|
|
|
|
type DeclaringTypeScope = ReturnType<typeof declaringTypeScope>;
|
|
type DeclaredMember =
|
|
| ManagedMemberInspection["methods"][number]
|
|
| ManagedMemberInspection["fields"][number];
|
|
|
|
/** Resolve tokens only in their own source, then test opposite nominal scope. */
|
|
const observedBy = (
|
|
own: DeclaringTypeScope,
|
|
opposite: DeclaringTypeScope,
|
|
member: DeclaredMember,
|
|
): boolean => {
|
|
if (opposite.selected === null) return true;
|
|
const name = own.names.get(member.declaring_type_token ?? "");
|
|
return name != null && opposite.selected.has(name);
|
|
};
|
|
|
|
/** Compare the nominal types the owner retained, independently of request spelling. */
|
|
const compareSelectedTypes = (
|
|
left: DeclaringTypeScope,
|
|
right: DeclaringTypeScope,
|
|
): SelectionAgreement => {
|
|
const leftNames = left.selected;
|
|
const rightNames = right.selected;
|
|
if (leftNames === null || rightNames === null)
|
|
return leftNames === rightNames ? "same" : "different";
|
|
if (!left.complete || !right.complete) return "unknown";
|
|
return leftNames.size === rightNames.size &&
|
|
[...leftNames].every((name) => rightNames.has(name))
|
|
? "same"
|
|
: "different";
|
|
};
|
|
|
|
/** Share the same nominal facts across pairing, absence and scope agreement. */
|
|
export const managedComparisonScope = (
|
|
left: ManagedMemberInspection,
|
|
right: ManagedMemberInspection,
|
|
) => {
|
|
const a = declaringTypeScope(left);
|
|
const b = declaringTypeScope(right);
|
|
return {
|
|
left: a,
|
|
right: b,
|
|
inLeft: (member: DeclaredMember) => observedBy(b, a, member),
|
|
inRight: (member: DeclaredMember) => observedBy(a, b, member),
|
|
agreement: compareSelectedTypes(a, b),
|
|
};
|
|
};
|
|
|
|
export type ManagedComparisonScope = ReturnType<typeof managedComparisonScope>;
|
|
|
|
/** Copy the source's typed capacity facts without retaining unrelated issue inventories. */
|
|
const resourceLimits = (
|
|
result: ManagedMemberInspection,
|
|
): NonNullable<ManagedMemberComparisonResult["left"]["resource_limits"]> =>
|
|
result.coverage.issues.flatMap(({ code, scope, detail, offset, limit }) =>
|
|
code === "resource-limit"
|
|
? [
|
|
{
|
|
code,
|
|
scope,
|
|
detail,
|
|
offset,
|
|
...(limit === undefined ? {} : { limit }),
|
|
},
|
|
]
|
|
: [],
|
|
);
|
|
|
|
export const sideManifest = (
|
|
side: ManagedMemberComparisonSide,
|
|
): ManagedMemberComparisonResult["left"] => {
|
|
const module = managedModuleRow(side.result);
|
|
return {
|
|
evidence_id: side.evidenceId,
|
|
artifact_sha256: side.result.artifact.sha256,
|
|
mvid: module?.mvid ?? null,
|
|
module_name: module?.name ?? null,
|
|
metadata_status: side.result.metadata.status,
|
|
methods_total: side.result.methods.length,
|
|
fields_total: side.result.fields.length,
|
|
resource_limits: resourceLimits(side.result),
|
|
};
|
|
};
|
|
|
|
export const buildComparisonSummary = (
|
|
items: readonly (
|
|
| ManagedMemberComparisonResult["methods"][number]
|
|
| ManagedMemberComparisonResult["fields"][number]
|
|
)[],
|
|
): ManagedMemberComparisonResult["summary"] => ({
|
|
unchanged: items.filter(({ status }) => status === "unchanged").length,
|
|
changed: items.filter(({ status }) => status === "changed").length,
|
|
added: items.filter(({ status }) => status === "added").length,
|
|
removed: items.filter(({ status }) => status === "removed").length,
|
|
unknown: items.filter(({ status }) => status === "unknown").length,
|
|
});
|
|
|
|
export const buildComparisonMatching = (
|
|
methodItems: readonly ManagedMemberComparisonResult["methods"][number][],
|
|
fieldItems: readonly ManagedMemberComparisonResult["fields"][number][],
|
|
): ManagedMemberComparisonResult["matching"] => ({
|
|
exact_il_signature: methodItems.filter(
|
|
({ match }) => match.basis === "exact-il-signature",
|
|
).length,
|
|
exact_signature: [...methodItems, ...fieldItems].filter(
|
|
({ match }) => match.basis === "exact-signature",
|
|
).length,
|
|
structural_method_shape: methodItems.filter(
|
|
({ match }) => match.basis === "structural-method-shape",
|
|
).length,
|
|
field_signature: fieldItems.filter(
|
|
({ match }) => match.basis === "field-signature",
|
|
).length,
|
|
ambiguous:
|
|
methodItems.filter(({ match }) => match.status === "ambiguous").length +
|
|
fieldItems.filter(({ match }) => match.status === "ambiguous").length,
|
|
unmatched: [...methodItems, ...fieldItems].filter(
|
|
({ match }) => match.status === "unmatched",
|
|
).length,
|
|
});
|
|
|
|
/** Carry each side's representation-budget diagnostic and its recovery. */
|
|
const capacityLimitations = (
|
|
left: ManagedMemberInspection,
|
|
right: ManagedMemberInspection,
|
|
): string[] => {
|
|
const exceeded = new Set(
|
|
(["left", "right"] as const).flatMap((side) =>
|
|
resourceLimits(side === "left" ? left : right).map(
|
|
({ scope, detail }) =>
|
|
`The ${side} managed member observation exceeded capacity at ${scope}: ${detail}. Its member collections are not examined to completion, so empty or missing members do not establish absence, addition or removal.`,
|
|
),
|
|
),
|
|
);
|
|
return exceeded.size === 0
|
|
? []
|
|
: [
|
|
...exceeded,
|
|
"Compare a smaller selection by inspecting both sides with the same type_names, or by passing --type to CLI compare-managed-members; a single selected type can still exceed capacity.",
|
|
];
|
|
};
|
|
|
|
export const comparisonLimitations = (
|
|
left: ManagedMemberInspection,
|
|
right: ManagedMemberInspection,
|
|
selectionAgreement: SelectionAgreement = managedComparisonScope(left, right)
|
|
.agreement,
|
|
): string[] => {
|
|
const limitations: string[] = [
|
|
"Metadata tokens are build-local coordinates; matched pairs are remaps, not persistent identities.",
|
|
"Methods pair within one declared type and name by exact CIL/signature, then signature, then structural shape; only then may exact CIL/signature or structural shape alone remap across declared types or names, never taking a member whose own declared type and name remain unpaired on the other side or whose declaring type is unresolved. Names alone are never a matching basis.",
|
|
"Fields pair by declared type, name, and signature, then remap by exact decoded signature alone under the same rule; an undecoded signature is compared only for an exact signature match, and an unmatched member with one stays unknown.",
|
|
];
|
|
if (
|
|
[left, right].some((report) =>
|
|
report.fields.some((field) => field.constant != null),
|
|
)
|
|
)
|
|
limitations.push(
|
|
"Field Constant-table defaults are not compared; field matching and change detection cover names, flags and signatures only.",
|
|
);
|
|
const namesTypes = (result: ManagedMemberInspection) =>
|
|
result.methods.some(
|
|
({ signature }) =>
|
|
signature.resolved_sha256 !== null &&
|
|
signature.resolved_sha256 !== signature.raw_sha256,
|
|
) ||
|
|
result.fields.some(
|
|
({ signature }) =>
|
|
signature.resolved_sha256 !== null &&
|
|
signature.resolved_sha256 !== signature.raw_sha256,
|
|
);
|
|
if (namesTypes(left) || namesTypes(right))
|
|
limitations.push(
|
|
"Signature type operands compare by namespace, name, and enclosing names only; defining assemblies and CLR type identity are not established by this comparison.",
|
|
);
|
|
if (left.coverage.state !== "complete" || right.coverage.state !== "complete")
|
|
limitations.push("At least one managed member observation is partial.");
|
|
limitations.push(...capacityLimitations(left, right));
|
|
if (selectionAgreement === "different")
|
|
limitations.push(
|
|
"The observations select different declaring types; a member outside the other side's selection is unknown, not added or removed.",
|
|
);
|
|
else if (selectionAgreement === "unknown")
|
|
limitations.push(
|
|
"Selected declaring-type scope agreement is unknown because at least one observation is incomplete or lacks resolved nominal type identities; matching request names do not establish the same observed scope.",
|
|
);
|
|
else if (left.selection !== null && left.types.length === 0)
|
|
limitations.push(
|
|
"Both observations select no observed declaring types; requested and unmatched names remain in each source selection.",
|
|
);
|
|
else if (left.selection !== null)
|
|
limitations.push(
|
|
`Both observations cover only the selected declaring types (${[...new Set(left.types.map(({ full_name }) => full_name))].join(", ")}); member totals and statuses describe those types, not the whole assembly.`,
|
|
);
|
|
if (!hasCompleteMethodRows(left) || !hasCompleteMethodRows(right))
|
|
limitations.push(
|
|
"At least one observation lacks a complete MethodDef row inventory; paged or unrecorded method scope cannot establish cross-build method absence. Row intervals are reported in method_rows and describe build-local selections.",
|
|
);
|
|
if (left.exported_types === null || right.exported_types === null)
|
|
limitations.push(
|
|
"At least one managed member observation did not examine ExportedType rows; its exported and forwarded types are unknown.",
|
|
);
|
|
if (
|
|
// optional-fact-default: null rows are reported as unknown by the limitation above.
|
|
(left.exported_types?.length ?? 0) > 0 ||
|
|
// optional-fact-default: null rows are reported as unknown by the limitation above.
|
|
(right.exported_types?.length ?? 0) > 0
|
|
)
|
|
limitations.push(
|
|
"ExportedType rows, including type forwarders, are observed but not compared; an unchanged comparison does not establish an unchanged exported or forwarded type set.",
|
|
);
|
|
limitations.push(
|
|
"ldstr literals are not compared; normalized CIL keeps #US tokens rather than decoded text, so an unchanged method does not establish unchanged string literals.",
|
|
);
|
|
return limitations;
|
|
};
|