diff --git a/docs/guides/managed/managed-code-analysis.md b/docs/guides/managed/managed-code-analysis.md index 60c7baf77f..47ab07f0f5 100644 --- a/docs/guides/managed/managed-code-analysis.md +++ b/docs/guides/managed/managed-code-analysis.md @@ -109,8 +109,8 @@ If there are competing string heaps and multiple Module rows, Module identity remains unknown even when a name index is zero. A known MVID can bound build-local token identity even when the Module name is unresolved. Unreadable names do not supply nominal member or type lookup keys. A nil or empty -TypeDef or MethodDef name leaves member inventory and cross-build comparison -coverage partial when the unreadable name could affect a match. A nil +TypeDef, MethodDef, or Field name leaves member inventory and cross-build +comparison coverage partial when the unreadable name could affect a match. A nil TypeDef namespace is valid and leaves the type name unqualified. If the metadata root declares both compressed (`#~`) and uncompressed (`#-`) diff --git a/src/domain/managed/managedMemberComparison.ts b/src/domain/managed/managedMemberComparison.ts index 66635b9fa6..68735a8467 100644 --- a/src/domain/managed/managedMemberComparison.ts +++ b/src/domain/managed/managedMemberComparison.ts @@ -291,6 +291,7 @@ const callEdgesByCaller = ( const fieldAccessesByCaller = ( result: ManagedMemberInspection, + emptyFieldTokens: ReadonlySet, ): ReadonlyMap< string, readonly ManagedMemberInspection["field_accesses"][number][] @@ -300,10 +301,15 @@ const fieldAccessesByCaller = ( ManagedMemberInspection["field_accesses"][number][] >(); for (const access of result.field_accesses) { + const observed = + emptyFieldTokens.has(access.field_token) && + access.target_identity_sha256 !== null + ? { ...access, target_identity_sha256: null } + : access; const callerAccesses = accesses.get(access.method_token); if (callerAccesses === undefined) - accesses.set(access.method_token, [access]); - else callerAccesses.push(access); + accesses.set(access.method_token, [observed]); + else callerAccesses.push(observed); } return accesses; }; @@ -330,8 +336,14 @@ export const compareManagedMembers = ( rightAssembly: right.result.assembly, leftCallEdgesByCaller: callEdgesByCaller(left.result), rightCallEdgesByCaller: callEdgesByCaller(right.result), - leftFieldAccessesByCaller: fieldAccessesByCaller(left.result), - rightFieldAccessesByCaller: fieldAccessesByCaller(right.result), + leftFieldAccessesByCaller: fieldAccessesByCaller( + left.result, + scope.left.emptyFieldTokens, + ), + rightFieldAccessesByCaller: fieldAccessesByCaller( + right.result, + scope.right.emptyFieldTokens, + ), }; const methodItems = buildMethodItems(methodMatches, itemContext); const fieldItems = buildFieldItems(fieldMatches, itemContext); diff --git a/src/domain/managed/managedMemberComparisonCoverage.ts b/src/domain/managed/managedMemberComparisonCoverage.ts index 81725c8a0c..9c21308fe3 100644 --- a/src/domain/managed/managedMemberComparisonCoverage.ts +++ b/src/domain/managed/managedMemberComparisonCoverage.ts @@ -85,8 +85,8 @@ const unavailableTypeNames = ( return unavailable; }; -/** One side's build-local TypeDef lookup and observed nominal selection. */ -const declaringTypeScope = (result: ManagedMemberInspection) => { +/** One side's nominal name availability and observed declaring-type selection. */ +const comparisonSideScope = (result: ManagedMemberInspection) => { const unavailable = unavailableTypeNames(result.types); const names = new Map( result.types.map((type) => [ @@ -96,15 +96,27 @@ const declaringTypeScope = (result: ManagedMemberInspection) => { ); // Historical Evidence may record invalid names with complete coverage. const hasEmptyTypeName = unavailable.size > 0; - const emptyMethodNames = new Set( - result.methods.filter(({ name }) => name === ""), + const emptyMemberNames = new Set(); + for (const definitions of [result.methods, result.fields]) + for (const member of definitions) + if (member.name === "") emptyMemberNames.add(member); + const emptyFieldTokens = new Set( + result.fields + .filter((field) => emptyMemberNames.has(field)) + .map(({ token }) => token), ); - const hasEmptyDefinitionName = hasEmptyTypeName || emptyMethodNames.size > 0; + // A selected method can reference a Field row outside the retained inventory. + for (const access of result.field_accesses) + if (access.field_name === "" && access.field_token.startsWith("0x04")) + emptyFieldTokens.add(access.field_token); + const hasEmptyDefinitionName = + hasEmptyTypeName || emptyMemberNames.size > 0 || emptyFieldTokens.size > 0; const metadataComplete = result.metadata.status === "complete" && !hasEmptyDefinitionName; return { names, - emptyMethodNames, + emptyMemberNames, + emptyFieldTokens, hasEmptyDefinitionName, metadataComplete, selected: @@ -119,15 +131,15 @@ const declaringTypeScope = (result: ManagedMemberInspection) => { }; }; -type DeclaringTypeScope = ReturnType; +type ComparisonSideScope = ReturnType; 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, + own: ComparisonSideScope, + opposite: ComparisonSideScope, member: DeclaredMember, ): boolean => { if (opposite.selected === null) return true; @@ -137,8 +149,8 @@ const observedBy = ( /** Compare the nominal types the owner retained, independently of request spelling. */ const compareSelectedTypes = ( - left: DeclaringTypeScope, - right: DeclaringTypeScope, + left: ComparisonSideScope, + right: ComparisonSideScope, ): SelectionAgreement => { const leftNames = left.selected; const rightNames = right.selected; @@ -156,8 +168,8 @@ export const managedComparisonScope = ( left: ManagedMemberInspection, right: ManagedMemberInspection, ) => { - const a = declaringTypeScope(left); - const b = declaringTypeScope(right); + const a = comparisonSideScope(left); + const b = comparisonSideScope(right); return { left: a, right: b, @@ -298,7 +310,7 @@ export const comparisonLimitations = ( limitations.push("At least one managed member observation is partial."); if (scope.left.hasEmptyDefinitionName || scope.right.hasEmptyDefinitionName) limitations.push( - "Recorded empty TypeDef or MethodDef names leave nominal identities unresolved. The comparison has partial name coverage even if a source reported complete metadata.", + "Recorded empty definition names leave nominal identities unresolved. The comparison has partial name coverage even if a source reported complete metadata.", ); limitations.push(...capacityLimitations(left, right)); if (scope.agreement === "different") diff --git a/src/domain/managed/managedMemberComparisonItems.ts b/src/domain/managed/managedMemberComparisonItems.ts index 8652e5d166..b9597d5197 100644 --- a/src/domain/managed/managedMemberComparisonItems.ts +++ b/src/domain/managed/managedMemberComparisonItems.ts @@ -484,7 +484,7 @@ const methodOnlyItem = ( ), unpaired: undecoded, ownIdentityUnavailable: identityUnavailable, - ownNameUnavailable: context.scope.left.emptyMethodNames.has(member.left), + ownNameUnavailable: context.scope.left.emptyMemberNames.has(member.left), opposite: "right", inventory: "method", }); @@ -508,7 +508,7 @@ const methodOnlyItem = ( ), unpaired: undecoded, ownIdentityUnavailable: identityUnavailable, - ownNameUnavailable: context.scope.right.emptyMethodNames.has(member.right), + ownNameUnavailable: context.scope.right.emptyMemberNames.has(member.right), opposite: "left", inventory: "method", }); @@ -540,7 +540,7 @@ const absenceLimitations = ( opposite: { readonly oppositeComplete: boolean; readonly ownIdentityUnavailable: boolean; - readonly ownNameUnavailable?: boolean; + readonly ownNameUnavailable: boolean; readonly unpaired: UndecodedOneSidedNames; readonly opposite: "left" | "right"; readonly inventory: "method" | "field"; @@ -550,7 +550,7 @@ const absenceLimitations = ( ? [ limitation( "unknown-within-incomplete-metadata", - "The recorded MethodDef name is empty, so its nominal identity is unavailable.", + `The recorded ${opposite.inventory === "method" ? "MethodDef" : "Field"} name is empty, so its nominal identity is unavailable.`, ), ] : opposite.ownIdentityUnavailable @@ -724,6 +724,7 @@ const fieldOnlyItem = ( ), unpaired: undecoded, ownIdentityUnavailable: identityUnavailable, + ownNameUnavailable: context.scope.left.emptyMemberNames.has(member.left), opposite: "right", inventory: "field", }); @@ -746,6 +747,7 @@ const fieldOnlyItem = ( ), unpaired: undecoded, ownIdentityUnavailable: identityUnavailable, + ownNameUnavailable: context.scope.right.emptyMemberNames.has(member.right), opposite: "left", inventory: "field", }); diff --git a/src/domain/managed/managedMemberComparisonMatch.ts b/src/domain/managed/managedMemberComparisonMatch.ts index 410d8ef1ce..c49e9d7a1a 100644 --- a/src/domain/managed/managedMemberComparisonMatch.ts +++ b/src/domain/managed/managedMemberComparisonMatch.ts @@ -510,26 +510,28 @@ export const keyMembers = ( } => { const declared = ( inspection: ManagedMemberInspection, - names: ReadonlyMap, + side: ManagedComparisonScope["left"], ): ((item: Method | Field) => DeclaredName) => { return (item) => { - if (!inspection.nesting_read) return null; - const digest = names.get(item.declaring_type_token ?? ""); + if (!inspection.nesting_read || side.emptyMemberNames.has(item)) + return null; + const digest = side.names.get(item.declaring_type_token ?? ""); return digest == null ? null : ["nominal-name-sha256", digest]; }; }; - const declaredLeft = declared(left.result, scope.left.names); - const declaredRight = declared(right.result, scope.right.names); + const declaredLeft = declared(left.result, scope.left); + const declaredRight = declared(right.result, scope.right); + const matchable = { + inLeft: (item: Method | Field) => + !scope.right.emptyMemberNames.has(item) && scope.inLeft(item), + inRight: (item: Method | Field) => + !scope.left.emptyMemberNames.has(item) && scope.inRight(item), + }; return { methodMatches: matchObserved( left.result.methods, right.result.methods, - { - inLeft: (item) => - !scope.right.emptyMethodNames.has(item) && scope.inLeft(item), - inRight: (item) => - !scope.left.emptyMethodNames.has(item) && scope.inRight(item), - }, + matchable, (a, b) => matchMethods( a, @@ -539,21 +541,13 @@ export const keyMembers = ( hasCompleteMethodRows(left.result) && hasCompleteMethodRows(right.result), ), - (item) => - keyMethod( - item, - scope.left.emptyMethodNames.has(item) ? null : declaredLeft(item), - ), - (item) => - keyMethod( - item, - scope.right.emptyMethodNames.has(item) ? null : declaredRight(item), - ), + (item) => keyMethod(item, declaredLeft(item)), + (item) => keyMethod(item, declaredRight(item)), ), fieldMatches: matchObserved( left.result.fields, right.result.fields, - scope, + matchable, (a, b) => matchFields( a, diff --git a/src/domain/managed/managedMetadataHeaps.ts b/src/domain/managed/managedMetadataHeaps.ts index 542614ee28..b769f3cd25 100644 --- a/src/domain/managed/managedMetadataHeaps.ts +++ b/src/domain/managed/managedMetadataHeaps.ts @@ -197,7 +197,7 @@ export const readMetadataString = ( export const readRequiredMetadataName = ( bytes: Buffer, layout: ManagedMetadataLayout, - table: "TypeDef" | "MethodDef", + table: "TypeDef" | "Field" | "MethodDef", token: string, { nameIndex, diff --git a/src/dotnet/ManagedFieldDefinitionRows.ts b/src/dotnet/ManagedFieldDefinitionRows.ts index e728d10917..a412aa6f22 100644 --- a/src/dotnet/ManagedFieldDefinitionRows.ts +++ b/src/dotnet/ManagedFieldDefinitionRows.ts @@ -2,6 +2,7 @@ import type { ManagedMetadataLayout } from "../domain/managed/managedMetadataLay import { metadataRowCursor, metadataToken, + readRequiredMetadataName, } from "../domain/managed/managedMetadataHeaps.js"; /** Scalar Field facts; consumers own heap admission and field selection. */ @@ -14,6 +15,7 @@ export const readFieldDefinitionRow = ( readonly rowOffset: number; readonly flags: number; readonly nameIndex: number; + readonly nameOffset: number; readonly signatureIndex: number; } => { // Layout admission bounds the complete row independently of its heap values. @@ -22,7 +24,24 @@ export const readFieldDefinitionRow = ( token: metadataToken(4, row), rowOffset: cursor.start, flags: cursor.u16(), + nameOffset: cursor.offset, nameIndex: cursor.readIndex(layout.stringIndexSize), signatureIndex: cursor.readIndex(layout.blobIndexSize), }; }; + +export const readFieldDefinitionName = ( + bytes: Buffer, + layout: ManagedMetadataLayout, + definition: Pick< + ReturnType, + "token" | "nameIndex" | "nameOffset" + >, +): string => + readRequiredMetadataName( + bytes, + layout, + "Field", + definition.token, + definition, + ); diff --git a/src/dotnet/ManagedMemberRows.ts b/src/dotnet/ManagedMemberRows.ts index 1b841a2f20..7c599907fe 100644 --- a/src/dotnet/ManagedMemberRows.ts +++ b/src/dotnet/ManagedMemberRows.ts @@ -1,4 +1,7 @@ -import { readFieldDefinitionRow } from "./ManagedFieldDefinitionRows.js"; +import { + readFieldDefinitionName, + readFieldDefinitionRow, +} from "./ManagedFieldDefinitionRows.js"; import { createManagedFieldConstantReader } from "./ManagedFieldConstants.js"; import { readMemberReferenceRowFacts } from "../domain/managed/managedMemberReferenceRows.js"; import { @@ -111,9 +114,9 @@ export const parseFields = ( ) continue; readManagedValue(() => { - const { token, rowOffset, flags, nameIndex, signatureIndex } = - readFieldDefinitionRow(bytes, layout, row); - const name = readMetadataString(bytes, layout, nameIndex); + const definition = readFieldDefinitionRow(bytes, layout, row); + const { token, rowOffset, flags, signatureIndex } = definition; + const name = readFieldDefinitionName(bytes, layout, definition); const owned = owner ?? 0; core.set(token, { token, @@ -507,10 +510,10 @@ export const readReferencedMemberCores = ( const declared = ranges[ownerOf(table, row) - 1]; const name = table === 4 - ? readMetadataString( + ? readFieldDefinitionName( bytes, layout, - readFieldDefinitionRow(bytes, layout, row).nameIndex, + readFieldDefinitionRow(bytes, layout, row), ) : readMethodDefinitionName( bytes, diff --git a/src/dotnet/ManagedNativeBoundaryHelpers.ts b/src/dotnet/ManagedNativeBoundaryHelpers.ts index 65bbf57a54..76be9eb72e 100644 --- a/src/dotnet/ManagedNativeBoundaryHelpers.ts +++ b/src/dotnet/ManagedNativeBoundaryHelpers.ts @@ -1,4 +1,7 @@ -import { readFieldDefinitionRow } from "./ManagedFieldDefinitionRows.js"; +import { + readFieldDefinitionName, + readFieldDefinitionRow, +} from "./ManagedFieldDefinitionRows.js"; import { readMethodDefinitionName, readMethodDefinitionRow, @@ -94,12 +97,9 @@ export const parseFields = ( const table = layout.table(4); for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) { readManagedValue(() => { - const { token, rowOffset, flags, nameIndex } = readFieldDefinitionRow( - bytes, - layout, - row, - ); - const name = readMetadataString(bytes, layout, nameIndex); + const definition = readFieldDefinitionRow(bytes, layout, row); + const { token, rowOffset, flags } = definition; + const name = readFieldDefinitionName(bytes, layout, definition); fields.set(token, { token, rowOffset, diff --git a/src/dotnet/ManagedNativeBoundaryInspector.test.ts b/src/dotnet/ManagedNativeBoundaryInspector.test.ts index 3c228b1409..e4682f827e 100644 --- a/src/dotnet/ManagedNativeBoundaryInspector.test.ts +++ b/src/dotnet/ManagedNativeBoundaryInspector.test.ts @@ -210,25 +210,36 @@ it.each([0, 2])( }, ); -it("reports field imports as declarations without inventing method implementations", () => { - const bytes = buildManagedPeFixture({ pinvoke: { memberForwardedRaw: 2 } }); - const result = inspectManagedNativeBoundariesBytes( - bytes, - managedPeFixtureTarget(bytes), - ); - expect(result.pinvoke_imports).toMatchObject([ - { - member_kind: "field", - member_token: "0x04000001", - member_name: "counter", - }, - ]); - expect( - result.native_implementations.every((item) => - item.token.startsWith("0x06"), - ), - ).toBe(true); -}); +it.each([ + { fieldName: "counter", memberName: "counter", status: "complete" }, + { fieldName: "", memberName: null, status: "partial" }, +])( + "preserves a field import declaration with a $status FieldDef name observation", + ({ fieldName, memberName, status }) => { + const bytes = buildManagedPeFixture({ + fieldName, + pinvoke: { memberForwardedRaw: 2 }, + }); + const result = inspectManagedNativeBoundariesBytes( + bytes, + managedPeFixtureTarget(bytes), + ); + expect(result.pinvoke_imports).toMatchObject([ + { + member_kind: "field", + member_token: "0x04000001", + member_name: memberName, + import_name: "MessageBoxW", + }, + ]); + expect(result.metadata.status).toBe(status); + expect( + result.native_implementations.every((item) => + item.token.startsWith("0x06"), + ), + ).toBe(true); + }, +); describe("managed native boundary inspection", () => { it("reports absent or malformed member metadata", () => { diff --git a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts index 5b8e6725cb..6110045d71 100644 --- a/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts +++ b/tests/boundary/providers/managed/managedMemberComparisonFromMetadata.test.ts @@ -31,12 +31,15 @@ describe("required managed definition names", () => { ["TypeDef", "empty", 2, 4, "Program", "0x02000001"], ["MethodDef", "nil", 6, 8, "Main", "0x06000001"], ["MethodDef", "empty", 6, 8, "Main", "0x06000001"], + ["Field", "nil", 4, 2, "counter", "0x04000001"], + ["Field", "empty", 4, 2, "counter", "0x04000001"], ] as const)( "keeps a %s %s name out of cross-build identity", (kind, encoding, table, column, name, token) => { const fixture = (mvidByte: number) => { const bytes = buildManagedPeFixture({ mvid: Buffer.alloc(16, mvidByte), + ...(kind === "Field" ? { ilBody: Buffer.from([0x06, 0x2a]) } : {}), }); const pe = readManagedPeLayout(bytes); if (pe.cli === null) throw new Error("Missing CLI metadata in fixture"); @@ -63,7 +66,7 @@ describe("required managed definition names", () => { } of [left, right]) { expect(result.metadata).toMatchObject({ status: "partial", - table_row_counts: { TypeDef: 1, MethodDef: 1 }, + table_row_counts: { TypeDef: 1, MethodDef: 1, Field: 1 }, }); expect(result.method_rows).toEqual({ offset: 0, count: 1, total: 1 }); expect(result.coverage.issues).toContainEqual( @@ -82,23 +85,35 @@ describe("required managed definition names", () => { declaring_type: null, }), ]); - } else { + } else if (kind === "MethodDef") { expect(result.types).toEqual([ expect.objectContaining({ full_name: "Fixture.Program" }), ]); expect(result.methods).toEqual([]); + } else { + expect(result.fields).toEqual([]); + expect(result.methods).toEqual([ + expect.objectContaining({ name: "Main" }), + ]); } } const comparison = compareManagedMembers(left.side, right.side); expect(comparison.coverage.status).toBe("partial"); expect(comparison.methods.map(({ status }) => status)).toEqual( - kind === "TypeDef" ? ["unknown", "unknown"] : [], + kind === "TypeDef" + ? ["unknown", "unknown"] + : kind === "Field" + ? ["unchanged"] + : [], ); - if (kind === "MethodDef") { + if (kind !== "TypeDef") { const named = inspect(buildManagedPeFixture(), "/fixture/named.dll"); - expect(compareManagedMembers(named, right.side).methods).toEqual([ - expect.objectContaining({ status: "unknown" }), - ]); + const comparisonWithKnown = compareManagedMembers(named, right.side); + expect( + kind === "Field" + ? comparisonWithKnown.fields + : comparisonWithKnown.methods, + ).toEqual([expect.objectContaining({ status: "unknown" })]); } }, ); @@ -131,6 +146,12 @@ describe("required managed definition names", () => { expect(comparison.methods).toEqual([ expect.objectContaining({ status: "unchanged" }), ]); + expect(comparison.fields).toEqual([ + expect.objectContaining({ + status: "unchanged", + match: expect.objectContaining({ basis: "field-signature" }), + }), + ]); }); }); @@ -814,6 +835,49 @@ describe("managed reference instruction comparison", () => { }); }); +it("keeps a saved CIL field target unknown when the direct Field name was empty", () => { + const sides = [0x11, 0x22].map((mvid) => + inspect( + buildManagedPeFixture({ + mvid: Buffer.alloc(16, mvid), + ilBody: Buffer.from([0x1e, 0x7e, 1, 0, 0, 4, 0x26, 0x2a]), + }), + `/fixture/archived-field-access-${String(mvid)}.dll`, + ), + ); + const [left, right] = sides; + if (left === undefined || right === undefined) + throw new Error("Missing paired fixtures"); + expect(compareManagedMembers(left, right).methods[0]?.status).toBe( + "unchanged", + ); + const historical = (side: typeof left) => ({ + ...side, + result: managedMemberInspectionSchema.parse({ + ...side.result, + fields: [], + field_accesses: side.result.field_accesses.map((edge) => ({ + ...edge, + field_name: "", + target_identity_sha256: + "667a82cbf4558dd1a05383d31082a7e637cdb2f3ac572d2fbfd4b6fe472bf168", + })), + }), + }); + const oldLeft = historical(left); + const oldRight = historical(right); + const compared = compareManagedMembers(oldLeft, oldRight); + expect(compared.coverage.status).toBe("partial"); + expect(compared.methods).toEqual([ + expect.objectContaining({ + status: "unknown", + limitations: expect.arrayContaining([ + expect.objectContaining({ code: "field-target-unavailable" }), + ]), + }), + ]); +}); + describe("managed field target comparison", () => { it("compares observed field targets for aligned field instructions", () => { const il = Buffer.from([0x7b, 1, 0, 0, 4, 0x26, 0x2a]); @@ -3601,7 +3665,7 @@ const comparedTokens = ( describe("historical managed definition names", () => { const archived = ( mvidByte: number, - missing: "TypeDef" | "MethodDef" | null, + missing: "TypeDef" | "MethodDef" | "Field" | null, ) => { const side = inspect( buildManagedPeFixture({ @@ -3630,6 +3694,10 @@ describe("historical managed definition names", () => { ...(missing === "TypeDef" ? { declaring_type: "Fixture." } : {}), ...(missing === "MethodDef" ? { name: "" } : {}), })), + fields: + missing === "Field" + ? result.fields.map((row) => ({ ...row, name: "" })) + : result.fields, }; return { ...side, @@ -3637,7 +3705,7 @@ describe("historical managed definition names", () => { }; }; - it.each(["TypeDef", "MethodDef"] as const)( + it.each(["TypeDef", "MethodDef", "Field"] as const)( "keeps a recorded empty %s name from establishing cross-build identity", (missing) => { const left = archived(0x11, missing); @@ -3650,12 +3718,14 @@ describe("historical managed definition names", () => { left_status: "complete", right_status: "complete", }); - expect( - comparison.methods.map(({ status, match }) => [status, match.basis]), - ).toEqual([ - ["unknown", "none"], - ["unknown", "none"], - ]); + const members = + missing === "Field" ? comparison.fields : comparison.methods; + expect(members.map(({ status, match }) => [status, match.basis])).toEqual( + [ + ["unknown", "none"], + ["unknown", "none"], + ], + ); expect(comparison.left).toMatchObject({ metadata_status: "complete", methods_total: 1,