From 21adb649ac27ea0bbc27272f8f876c08cd335bce Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 05:53:44 +0800 Subject: [PATCH] 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 --- docs/guides/managed/managed-code-analysis.md | 5 + src/domain/managed/managedMemberComparison.ts | 35 ++++- .../managed/managedMemberComparisonItems.ts | 119 +++++++++++++---- .../cli/managedMemberComparisonCli.test.ts | 2 +- .../managed/managedMemberComparison.test.ts | 8 +- ...anagedMemberComparisonFromMetadata.test.ts | 125 ++++++++++++------ ...nagedMemberComparisonPartialBodies.test.ts | 4 +- 7 files changed, 227 insertions(+), 71 deletions(-) diff --git a/docs/guides/managed/managed-code-analysis.md b/docs/guides/managed/managed-code-analysis.md index d78fad056d..35f883f59c 100644 --- a/docs/guides/managed/managed-code-analysis.md +++ b/docs/guides/managed/managed-code-analysis.md @@ -677,6 +677,11 @@ signature has the other member kind is malformed and cannot establish an unchanged signature. Comparison retains exact byte-based pairs for malformed signatures, including empty, truncated, or invalid headers, but reports them as unknown with a `signature-malformed` limitation when no change is observed. +Each method and field comparison item states its limitations as +`{code, side?, message}` objects: `code` names the reason, `side` names the +other inventory when the reason concerns it (for example +`unknown-within-incomplete-metadata` with `side: "right"`), and `message` +explains it. Read the code rather than the message text. Runtime-provided methods have the Runtime code type or the InternalCall implementation flag, as core library FCalls do. They are counted separately in `native_implementations.runtime_provided`; they have no file-backed native body diff --git a/src/domain/managed/managedMemberComparison.ts b/src/domain/managed/managedMemberComparison.ts index b1bde592b8..9c79164d71 100644 --- a/src/domain/managed/managedMemberComparison.ts +++ b/src/domain/managed/managedMemberComparison.ts @@ -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( diff --git a/src/domain/managed/managedMemberComparisonItems.ts b/src/domain/managed/managedMemberComparisonItems.ts index e383d191c8..0c7dfc6c03 100644 --- a/src/domain/managed/managedMemberComparisonItems.ts +++ b/src/domain/managed/managedMemberComparisonItems.ts @@ -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 = | { 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.", + ), ] : []), ], diff --git a/tests/boundary/cli/managedMemberComparisonCli.test.ts b/tests/boundary/cli/managedMemberComparisonCli.test.ts index 741a6602cb..7a744e514c 100644 --- a/tests/boundary/cli/managedMemberComparisonCli.test.ts +++ b/tests/boundary/cli/managedMemberComparisonCli.test.ts @@ -264,7 +264,7 @@ cliTest( confidence: "exact", }), limitations: malformed - ? [expect.stringMatching(/^signature-malformed:/)] + ? [expect.objectContaining({ code: "signature-malformed" })] : [], }), ]); diff --git a/tests/boundary/providers/managed/managedMemberComparison.test.ts b/tests/boundary/providers/managed/managedMemberComparison.test.ts index 7e519aa446..f55b67754e 100644 --- a/tests/boundary/providers/managed/managedMemberComparison.test.ts +++ b/tests/boundary/providers/managed/managedMemberComparison.test.ts @@ -449,8 +449,8 @@ describe("managed nested type names", () => { const warned = comparison.methods.map(({ left, right, limitations }) => [ left?.token ?? null, right?.token ?? null, - limitations.some((limitation) => - limitation.startsWith("counterpart-signature-not-decoded"), + limitations.some( + ({ code }) => code === "counterpart-signature-not-decoded", ), ]); @@ -600,7 +600,9 @@ describe("managed call-target comparison", () => { expect(report.methods[0]).toMatchObject({ status: "changed", dimensions: expect.arrayContaining(["call-target", "availability"]), - limitations: [expect.stringContaining("call targets are unavailable")], + limitations: [ + expect.objectContaining({ code: "call-target-unavailable" }), + ], }); const unavailableEdges = observe( diff --git a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts index a9e8292de2..8ae445c1a5 100644 --- a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts +++ b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts @@ -1104,7 +1104,9 @@ describe("managed LocalVarSig comparison", () => { status: "changed", dimensions: ["metadata"], match: { basis: "exact-il-signature" }, - limitations: [expect.stringContaining("encoding difference")], + limitations: [ + expect.objectContaining({ code: "local-signature-bytes-changed" }), + ], }); }); @@ -1127,9 +1129,7 @@ describe("managed LocalVarSig comparison", () => { status: "changed", dimensions: ["metadata", "availability"], limitations: [ - expect.stringContaining( - "Local variable signature identity is unknown", - ), + expect.objectContaining({ code: "local-signature-unknown" }), ], }); const sameHeader = observe( @@ -1289,6 +1289,10 @@ describe("managed member comparison", () => { status: "changed", match: { status: "matched", basis: "exact-signature" }, dimensions: ["cil", "availability"], + limitations: [ + expect.objectContaining({ code: "call-target-unavailable" }), + expect.objectContaining({ code: "field-target-unavailable" }), + ], }); }); @@ -1327,6 +1331,40 @@ describe("managed member comparison", () => { }); }); +describe("managed member comparison limitation reasons", () => { + it("states each limitation as a code with its explanation and refuses bare text", () => { + const left = inspect(buildManagedPeFixture(), "/tmp/left.dll"); + const right = inspect( + buildManagedPeFixture({ + ilBody: Buffer.from([ + 0x32, 0x02, 0x7b, 0x02, 0x00, 0x00, 0x04, 0x28, 0x02, 0x00, 0x00, + 0x0a, 0x2a, + ]), + }), + "/tmp/right.dll", + ); + const result = compareManagedMembers( + { evidenceId: left.evidenceId, result: left.result }, + { evidenceId: right.evidenceId, result: right.result }, + ); + expect(managedMemberComparisonResultSchema.parse(result)).toEqual(result); + expect(result.methods[0]?.limitations).toEqual([ + { code: "call-target-unavailable", message: expect.any(String) }, + { code: "field-target-unavailable", message: expect.any(String) }, + ]); + // A limitation recorded as bare text has no reason and is refused. + expect( + managedMemberComparisonResultSchema.safeParse({ + ...result, + methods: result.methods.map((item) => ({ + ...item, + limitations: item.limitations.map(({ message }) => message), + })), + }).success, + ).toBe(false); + }); +}); + describe("managed member comparison with equal decoded fingerprints", () => { it.each([ { name: "Main", basis: "exact-signature" }, @@ -1519,7 +1557,10 @@ describe("managed member comparison uncertainty", () => { left: { token: "0x06000001" }, right: null, limitations: [ - expect.stringContaining("unknown-within-incomplete-metadata"), + expect.objectContaining({ + code: "unknown-within-incomplete-metadata", + side: "right", + }), ], }); expect(result.fields[0]).toMatchObject({ @@ -1527,7 +1568,10 @@ describe("managed member comparison uncertainty", () => { left: null, right: { token: "0x04000001" }, limitations: [ - expect.stringContaining("unknown-within-incomplete-metadata"), + expect.objectContaining({ + code: "unknown-within-incomplete-metadata", + side: "left", + }), ], }); expect(result.coverage).toEqual({ @@ -1585,9 +1629,7 @@ describe("managed member comparison uncertainty", () => { candidate_left_tokens: ["0x04000001", "0x04000002"], candidate_right_tokens: ["0x04000001", "0x04000002"], }), - limitations: [ - "Multiple managed fields share the same signature; REA did not guess a token remap.", - ], + limitations: [expect.objectContaining({ code: "ambiguous-signature" })], }), ]); }); @@ -1650,7 +1692,7 @@ it.each([ expect(item).toMatchObject({ status: "unknown", match: { status: "matched", confidence: "exact" }, - limitations: [expect.stringMatching(/^signature-malformed:/)], + limitations: [expect.objectContaining({ code: "signature-malformed" })], }); }, ); @@ -1767,7 +1809,9 @@ describe("managed member comparison of undecoded signatures", () => { expect(item).toMatchObject({ status: "unknown", match: { status: "unmatched" }, - limitations: [expect.stringContaining("signature-not-decoded")], + limitations: [ + expect.objectContaining({ code: "signature-not-decoded" }), + ], }); }); @@ -1791,10 +1835,10 @@ describe("managed member comparison of undecoded signatures", () => { status: "unknown", match: { status: "unmatched" }, limitations: [ - expect.stringMatching( + expect.objectContaining( item.left === null - ? /^signature-not-decoded:/ - : /^counterpart-signature-not-decoded: The right (method|field) inventory/, + ? { code: "signature-not-decoded" } + : { code: "counterpart-signature-not-decoded", side: "right" }, ), ], }); @@ -1843,16 +1887,17 @@ describe("managed member comparison of ambiguous undecoded signatures", () => { basis: "exact-il-signature", }), limitations: [ - "Multiple managed methods share the same CIL and signature; REA did not guess a token remap.", + expect.objectContaining({ code: "ambiguous-il-signature" }), ], }), expect.objectContaining({ status: "unknown", left: expect.objectContaining({ token: "0x06000002" }), limitations: [ - expect.stringMatching( - /^counterpart-signature-not-decoded: The right method inventory has an unpaired member/u, - ), + expect.objectContaining({ + code: "counterpart-signature-not-decoded", + side: "right", + }), ], }), ]), @@ -2155,7 +2200,7 @@ describe("managed member comparison remaps around kept identities", () => { basis: "structural-method-shape", }), limitations: [ - "Multiple managed methods share the same structural shape; REA did not guess a token remap.", + expect.objectContaining({ code: "ambiguous-method-shape" }), ], }), ]); @@ -2562,7 +2607,7 @@ it("keeps a lone ownerless member unknown despite an identical payload", () => { candidate_right_tokens: [ownerless.token], }, limitations: [ - expect.stringContaining("Declared type identity remains unresolved"), + expect.objectContaining({ code: "declaring-type-name-not-resolved" }), ], }); expect(result.summary).toMatchObject({ @@ -3176,16 +3221,18 @@ describe("managed member comparison of unresolved signatures", () => { methodSignature: Buffer.from([0x00, 0x00, 0x12, leftTypes.program]), }; const methodLimitations = (result: ReturnType) => - result.methods.map(({ status, limitations }) => [status, limitations]); + result.methods.map(({ status, limitations }) => [ + status, + limitations.map(({ code, side }) => ({ code, side })), + ]); + const notResolved = [{ code: "signature-not-resolved" }]; it("does not establish unchanged signatures from identical unresolved row bytes", () => { const result = compareBuilds(unresolvedAt(1), { ...unresolvedAt(1), typeSpecSignatures: [...typeSpecs].reverse(), }); - expect(methodLimitations(result)).toEqual([ - ["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]], - ]); + expect(methodLimitations(result)).toEqual([["unknown", notResolved]]); }); it("retains a known CIL change beside an unresolved signature", () => { @@ -3193,9 +3240,7 @@ describe("managed member comparison of unresolved signatures", () => { ...unresolvedAt(1), ilBody: Buffer.from([0x0a, 0x17, 0x2a]), }); - expect(methodLimitations(result)).toEqual([ - ["changed", [expect.stringMatching(/^signature-not-resolved:/u)]], - ]); + expect(methodLimitations(result)).toEqual([["changed", notResolved]]); expect(result.methods[0]?.dimensions).toContain("cil"); }); @@ -3208,7 +3253,9 @@ describe("managed member comparison of unresolved signatures", () => { expect(result.fields).toEqual([ expect.objectContaining({ status: "unknown", - limitations: [expect.stringMatching(/^signature-not-resolved:/u)], + limitations: [ + expect.objectContaining({ code: "signature-not-resolved" }), + ], }), ]); }); @@ -3230,8 +3277,8 @@ describe("managed member comparison of unresolved signatures", () => { compareBuilds(unresolvedAt(2), unresolvedAt(1)), ]) expect(methodLimitations(result)).toEqual([ - ["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]], - ["unknown", [expect.stringMatching(/^signature-not-resolved:/u)]], + ["unknown", notResolved], + ["unknown", notResolved], ]); }); @@ -3248,25 +3295,19 @@ describe("managed member comparison of unresolved signatures", () => { (leftItem === null) === (unresolvedSide === "left") ? "resolved" : "unresolved", - limitations, + limitations.map(({ code, side }) => ({ code, side })), ]), ).toEqual( expect.arrayContaining([ - [ - "unknown", - "unresolved", - [expect.stringMatching(/^signature-not-resolved:/u)], - ], + ["unknown", "unresolved", notResolved], [ "unknown", "resolved", [ - expect.stringMatching( - new RegExp( - `^counterpart-signature-not-resolved: The ${unresolvedSide} method inventory`, - "u", - ), - ), + { + code: "counterpart-signature-not-resolved", + side: unresolvedSide, + }, ], ], ]), diff --git a/tests/boundary/providers/managed/managedMemberComparisonPartialBodies.test.ts b/tests/boundary/providers/managed/managedMemberComparisonPartialBodies.test.ts index ac5f528cd3..4e2b97e189 100644 --- a/tests/boundary/providers/managed/managedMemberComparisonPartialBodies.test.ts +++ b/tests/boundary/providers/managed/managedMemberComparisonPartialBodies.test.ts @@ -55,7 +55,9 @@ describe("managed member partial body comparison", () => { expect(compareManagedMembers(left, right).methods[0]).toMatchObject({ status: "changed", dimensions: ["metadata", "body-coverage"], - limitations: expect.arrayContaining([expect.stringContaining("unknown")]), + limitations: expect.arrayContaining([ + expect.objectContaining({ code: "body-unavailable" }), + ]), }); });