Files
reverse-engineering-anything/src/domain/managed/managedMemberComparisonCoverage.ts
T
morluto a4bf59f661 fix(managed): preserve Module identity with an unresolved name (#12265)
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.
2026-11-19 06:08:59 -05:00

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;
};