feat(managed)!: state member comparison item limitations as tagged reason objects (#11177)

* feat(managed): give each member comparison limitation a structured reason

* feat(managed)!: state member comparison item limitations as tagged objects

Each method and field comparison item limitation is now {code, side?, message}
instead of a prefixed sentence beside a parallel limitation_reasons list.

BREAKING CHANGE: compare_managed_members item limitations are objects, not
strings, and limitation_reasons is removed. Read limitations[].code (and side)
instead of matching message prefixes such as "signature-not-resolved:".
Comparison Evidence written by earlier builds is refused; recreate it.

* test(managed): assert limitation codes instead of banning a message prefix
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 05:53:44 +08:00
1 parent f270a5cac1
commit 21adb649ac
7 files changed
+227 -71

No files matched your search

+34 -1
View File
@@ -132,9 +132,42 @@ const comparisonItemSchema = <
}),
]);
/** Stable codes for why one comparison item's facts stayed limited. */
export const MANAGED_MEMBER_COMPARISON_LIMITATION_CODES = [
"declaring-type-name-not-resolved",
"counterpart-declaring-type-name-not-resolved",
"unknown-within-incomplete-metadata",
"signature-not-decoded",
"counterpart-signature-not-decoded",
"signature-not-resolved",
"counterpart-signature-not-resolved",
"signature-malformed",
"ambiguous-signature",
"ambiguous-il-signature",
"ambiguous-method-shape",
"local-signature-unknown",
"local-signature-bytes-changed",
"body-unavailable",
"call-target-unavailable",
"field-target-unavailable",
"catch-type-unavailable",
] as const;
/** One reason a comparison item's facts stayed limited, with its explanation. */
const comparisonItemLimitationSchema = z.strictObject({
code: z.enum(MANAGED_MEMBER_COMPARISON_LIMITATION_CODES),
side: z
.enum(["left", "right"])
.optional()
.describe(
"The inventory this limitation concerns when it is the other side's, such as an incomplete or ambiguous counterpart inventory.",
),
message: nonEmptyTextSchema,
});
const comparisonItemContextShape = {
evidence_links: z.array(evidenceIdSchema).length(2),
limitations: z.array(nonEmptyTextSchema),
limitations: z.array(comparisonItemLimitationSchema),
};
const methodComparisonItemSchema = comparisonItemSchema(
@@ -28,6 +28,15 @@ type UnmatchedComparison = Extract<
{ readonly status: "unmatched" }
>;
type Limitation = MethodItem["limitations"][number];
const limitation = (
code: Limitation["code"],
message: string,
side?: "left" | "right",
): Limitation =>
side === undefined ? { code, message } : { code, side, message };
type OneSided<Item> =
| { readonly left: Item; readonly right?: never }
| { readonly left?: never; readonly right: Item };
@@ -533,43 +542,68 @@ const absenceLimitations = (
readonly opposite: "left" | "right";
readonly inventory: "method" | "field";
},
): string[] => [
): Limitation[] => [
...(opposite.ownIdentityUnavailable
? [
"declaring-type-name-not-resolved: Declared type identity could not be resolved; a bare display name cannot establish a counterpart or absence.",
limitation(
"declaring-type-name-not-resolved",
"Declared type identity could not be resolved; a bare display name cannot establish a counterpart or absence.",
),
]
: []),
...(opposite.unpaired.unknownOwners[opposite.opposite].has(member.name)
? [
`counterpart-declaring-type-name-not-resolved: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired same-named member with unresolved enclosing-name identity, so absence was not established.`,
limitation(
"counterpart-declaring-type-name-not-resolved",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired same-named member with unresolved enclosing-name identity, so absence was not established.`,
opposite.opposite,
),
]
: []),
...(opposite.oppositeComplete
? []
: [
`unknown-within-incomplete-metadata: The ${opposite.opposite} ${opposite.inventory} inventory is incomplete, so absence was not observed.`,
limitation(
"unknown-within-incomplete-metadata",
`The ${opposite.opposite} ${opposite.inventory} inventory is incomplete, so absence was not observed.`,
opposite.opposite,
),
]),
...(member.signature.parse_status === "decoded"
? []
: [
`signature-not-decoded: The member's ${member.signature.parse_status} signature was compared only by exact declared type, name, and signature bytes, so a changed or renamed counterpart could not be sought.`,
limitation(
"signature-not-decoded",
`The member's ${member.signature.parse_status} signature was compared only by exact declared type, name, and signature bytes, so a changed or renamed counterpart could not be sought.`,
),
]),
...(member.signature.parse_status === "decoded" &&
opposite.unpaired.undecoded[opposite.opposite].has(identity)
? [
`counterpart-signature-not-decoded: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature was not decoded, so it may be this member with a changed signature.`,
limitation(
"counterpart-signature-not-decoded",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature was not decoded, so it may be this member with a changed signature.`,
opposite.opposite,
),
]
: []),
...(unresolved(member)
? [
`signature-not-resolved: The member's signature names a type REA could not name, so it was compared by raw bytes, which name types by build-local metadata row; a counterpart whose referenced type moved rows could not be found.`,
limitation(
"signature-not-resolved",
`The member's signature names a type REA could not name, so it was compared by raw bytes, which name types by build-local metadata row; a counterpart whose referenced type moved rows could not be found.`,
),
]
: []),
...(member.signature.parse_status === "decoded" &&
!unresolved(member) &&
opposite.unpaired.unresolved[opposite.opposite].has(identity)
? [
`counterpart-signature-not-resolved: The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature names a type REA could not name, so it may be this member.`,
limitation(
"counterpart-signature-not-resolved",
`The ${opposite.opposite} ${opposite.inventory} inventory has an unpaired member with the same declared type and name whose signature names a type REA could not name, so it may be this member.`,
opposite.opposite,
),
]
: []),
];
@@ -583,17 +617,23 @@ const unresolved = (member: Method | Field): boolean =>
const pairedSignatureLimitations = (
left: Method | Field,
right: Method | Field,
): string[] => {
): Limitation[] => {
if (
left.signature.parse_status === "malformed" ||
right.signature.parse_status === "malformed"
)
return [
"signature-malformed: At least one signature is malformed; equal signature bytes do not establish an unchanged member signature.",
limitation(
"signature-malformed",
"At least one signature is malformed; equal signature bytes do not establish an unchanged member signature.",
),
];
return unresolved(left) || unresolved(right)
? [
"signature-not-resolved: At least one signature names a type REA could not resolve; equal build-local row bytes do not establish equivalent signature types.",
limitation(
"signature-not-resolved",
"At least one signature names a type REA could not resolve; equal build-local row bytes do not establish equivalent signature types.",
),
]
: [];
};
@@ -717,16 +757,31 @@ const ambiguityLimitation = (
members: "methods" | "fields",
basis: MethodItem["match"]["basis"],
identityUnavailable: boolean,
): string =>
): Limitation =>
identityUnavailable
? "declaring-type-name-not-resolved: Declared type identity remains unresolved; REA did not guess a counterpart from display names, signatures or CIL."
? limitation(
"declaring-type-name-not-resolved",
"Declared type identity remains unresolved; REA did not guess a counterpart from display names, signatures or CIL.",
)
: basis === "exact-signature"
? `Multiple managed ${members} share the same signature; REA did not guess declared ownership or a token remap.`
? limitation(
"ambiguous-signature",
`Multiple managed ${members} share the same signature; REA did not guess declared ownership or a token remap.`,
)
: basis === "exact-il-signature"
? "Multiple managed methods share the same CIL and signature; REA did not guess a token remap."
? limitation(
"ambiguous-il-signature",
"Multiple managed methods share the same CIL and signature; REA did not guess a token remap.",
)
: members === "methods"
? "Multiple managed methods share the same structural shape; REA did not guess a token remap."
: "Multiple managed fields share the same signature; REA did not guess a token remap.";
? limitation(
"ambiguous-method-shape",
"Multiple managed methods share the same structural shape; REA did not guess a token remap.",
)
: limitation(
"ambiguous-signature",
"Multiple managed fields share the same signature; REA did not guess a token remap.",
);
/** Local signature bytes prove identity only without metadata or declaring-context dependencies. */
const compareLocalSignatures = (
@@ -831,32 +886,50 @@ export const buildMethodItems = (
...signatureLimitations,
...(locals.unknown
? [
"Local variable signature identity is unknown because validated context-free signature facts are unavailable or the signature requires metadata or declaring context; build-local tokens and raw bytes do not establish equivalent local types across artifacts.",
limitation(
"local-signature-unknown",
"Local variable signature identity is unknown because validated context-free signature facts are unavailable or the signature requires metadata or declaring context; build-local tokens and raw bytes do not establish equivalent local types across artifacts.",
),
]
: []),
...(locals.changed
? [
"The validated context-free LocalVarSig bytes changed; this records an encoding difference without asserting a semantic type change.",
limitation(
"local-signature-bytes-changed",
"The validated context-free LocalVarSig bytes changed; this records an encoding difference without asserting a semantic type change.",
),
]
: []),
...(bodyUnknown
? [
"Method body facets are unknown because at least one side has unavailable or partial body data.",
limitation(
"body-unavailable",
"Method body facets are unknown because at least one side has unavailable or partial body data.",
),
]
: []),
...(callTargetUnknown
? [
"One or more call targets are unavailable because the observed method edges do not cover aligned call instructions or lack a resolved nominal target identity or instruction site.",
limitation(
"call-target-unavailable",
"One or more call targets are unavailable because the observed method edges do not cover aligned call instructions or lack a resolved nominal target identity or instruction site.",
),
]
: []),
...(fieldTargetUnknown
? [
"One or more field targets are unavailable because observed field accesses do not cover aligned field instructions or lack a resolved nominal target identity or instruction site.",
limitation(
"field-target-unavailable",
"One or more field targets are unavailable because observed field accesses do not cover aligned field instructions or lack a resolved nominal target identity or instruction site.",
),
]
: []),
...(exceptionTargetUnknown
? [
"One or more catch type identities are unavailable because local tokens or TypeRef resolution scopes do not establish cross-build identity.",
limitation(
"catch-type-unavailable",
"One or more catch type identities are unavailable because local tokens or TypeRef resolution scopes do not establish cross-build identity.",
),
]
: []),
],