diff --git a/docs/guides/native/native-initializers.md b/docs/guides/native/native-initializers.md index 9a1813a8a0..62354dfdbd 100644 --- a/docs/guides/native/native-initializers.md +++ b/docs/guides/native/native-initializers.md @@ -172,8 +172,17 @@ visible. `offset` and `limit` page the ordered list (default limit 64, maximum 4096). `coverage.examined_entries` counts every slot read, including omitted sentinels, and `total_entries` (the listed entries) is set when the inventory -is complete. At most 65536 slots are examined; beyond that, or when relocation -coverage is unknown, `status` and `coverage.status` are `incomplete`. +is complete. At most 65536 slots are examined. Any gap makes `status` +`incomplete`, and `coverage.status` says which kind it is: + +- `partial`: declared slots or names were examined but not reported. Examples + are the 65536-slot budget, an array that is compressed, not file-backed, + has no size tag or has trailing bytes, and a name over the 1024-byte budget. +- `unknown`: whether the listed facts are complete cannot be determined. + Examples are unknown relocation, fixup, symbol or mapping coverage, a + duplicate dynamic tag and a `PT_DYNAMIC` without `DT_NULL`. + +When both kinds occur, `coverage.status` is `unknown`. ELF symbol names come from at most 65536 symbols across all `SHT_SYMTAB` and `SHT_DYNSYM` tables together, and section `REL` / `RELA` relocations from at diff --git a/docs/specs/native/native-initializers/spec.md b/docs/specs/native/native-initializers/spec.md index 0b5371c669..7e9c3ce50d 100644 --- a/docs/specs/native/native-initializers/spec.md +++ b/docs/specs/native/native-initializers/spec.md @@ -69,6 +69,11 @@ slot's location, resolved target and how that target was obtained. The - Paging uses `offset` / `limit` (default 64, maximum 4096) over a stable ordered index. `coverage.examined_entries` counts every slot read, including omitted sentinels; `total_entries` is set only when the inventory is complete. + `coverage.status` is `partial` when declared slots or names were examined but + not reported (budgets, unreadable arrays, withheld names) and `unknown` when + completeness cannot be determined (relocation, fixup, symbol or mapping + coverage, duplicate or unterminated dynamic tags); unknown wins when both + occur. - Malformed headers, multiple `PT_DYNAMIC` segments and truncated dynamic sections fail without partial success. Cancellation is honored during slot collection, the section relocation walk and the dynamic relocation walk, diff --git a/scripts/verify/baselines/local-completeness-enum.json b/scripts/verify/baselines/local-completeness-enum.json index ed0913ee3f..744d8f9dfd 100644 --- a/scripts/verify/baselines/local-completeness-enum.json +++ b/scripts/verify/baselines/local-completeness-enum.json @@ -13,7 +13,6 @@ "src/domain/javascript/javascriptExportShapeComparisonSchemas.ts": 1, "src/domain/javascript/javascriptRouteInventory.ts": 1, "src/domain/javascript/javascriptStaticCoverage.ts": 1, - "src/domain/native/nativeInitializers.ts": 1, "src/domain/sqlite/sqliteDatabase.ts": 1, "src/domain/wasm/wasmArtifact.ts": 1, "src/domain/windows/ntfsMftAttributes.ts": 1 diff --git a/src/application/binaryDiagnostics/NativeInitializersService.test.ts b/src/application/binaryDiagnostics/NativeInitializersService.test.ts index 5031d89651..b89ef02ad5 100644 --- a/src/application/binaryDiagnostics/NativeInitializersService.test.ts +++ b/src/application/binaryDiagnostics/NativeInitializersService.test.ts @@ -155,7 +155,8 @@ it("rejects an architecture selection when the report has no universal slice", a it.each([ ["a page that does not match the request", { offset: 1 }], ["a returned count that differs from the entries", { returned_entries: 0 }], - ["complete coverage on an incomplete report", { status: "incomplete" }], + ["partial coverage on a parsed report", { status: "partial" }], + ["unknown coverage on a parsed report", { status: "unknown" }], ] as const)("rejects provider output with %s", async (_label, coverage) => { const result = await serviceFor({ ...report, diff --git a/src/domain/native/nativeInitializers.ts b/src/domain/native/nativeInitializers.ts index 8bf20d40e1..b9da2da845 100644 --- a/src/domain/native/nativeInitializers.ts +++ b/src/domain/native/nativeInitializers.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { coverageStatusSchema } from "../coverage.js"; import { machoSliceArchitectureSchema } from "../apple/machoTargetSelection.js"; import { @@ -116,7 +117,13 @@ const entrySchema = z.strictObject({ export type NativeInitializerEntry = z.infer; const coverageSchema = z.strictObject({ - status: z.enum(["complete", "incomplete"]), + /** + * `partial` when declared slots or names were examined but not reported + * (budgets, unreadable arrays, withheld names); `unknown` when whether the + * listed facts are complete cannot be determined (relocation, fixup, symbol + * or mapping coverage, an unterminated dynamic table). + */ + status: coverageStatusSchema, examined_entries: z.number().int().min(0).max(MAX_NATIVE_INITIALIZER_ENTRIES), total_entries: z .number() diff --git a/src/native/initializers/ElfInitializers.ts b/src/native/initializers/ElfInitializers.ts index 5f1c2c0ecb..5ab5927f58 100644 --- a/src/native/initializers/ElfInitializers.ts +++ b/src/native/initializers/ElfInitializers.ts @@ -1,5 +1,9 @@ import { setImmediate as immediate } from "node:timers/promises"; import { assertArtifactReadActive } from "../../resources/index.js"; +import { + joinCoverageStatus, + type CoverageStatus, +} from "../../domain/coverage.js"; import { readElfDynamicEntry } from "../../domain/elfDynamicEntry.js"; import { elfArchitecture } from "../../domain/elfFixedHeader.js"; import { @@ -113,14 +117,21 @@ interface ElfScan { readonly machine: number; readonly relocatable: boolean; readonly notes: InitializerNotes; - incomplete: boolean; + /** Known gaps (`partial`) and undetermined facts (`unknown`) noted so far. */ + coverage: CoverageStatus; /** Array slots still walkable across every source, so a declared size never sets the work. */ slotBudget: number; } -const note = (scan: ElfScan, message: string, incomplete = true): void => { +/** + * Record an observation and its effect on coverage: `partial` when declared + * slots or names were examined but not reported, `unknown` when whether the + * listed facts are complete cannot be determined, `complete` for a note that + * loses nothing. + */ +const note = (scan: ElfScan, message: string, effect: CoverageStatus): void => { scan.notes.add(message); - if (incomplete) scan.incomplete = true; + scan.coverage = joinCoverageStatus([scan.coverage, effect]); }; const wordOf = (bits: 32 | 64): number => bits / 8; @@ -129,7 +140,7 @@ const wordOf = (bits: 32 | 64): number => bits / 8; const isSentinel = (value: bigint, bits: 32 | 64): boolean => value === 0n || value === (1n << BigInt(bits)) - 1n; -/** Read the consumed DT_* tags. The first duplicate wins. A missing DT_NULL stays incomplete. */ +/** Read the consumed DT_* tags. The first duplicate wins. A missing DT_NULL leaves coverage unknown. */ const readDynamicTags = ( scan: ElfScan, segment: { readonly offset: bigint; readonly size: bigint } | undefined, @@ -177,6 +188,7 @@ const readDynamicTags = ( note( scan, `Duplicate dynamic tag ${parsed.value.tag} was ignored after the first value.`, + "unknown", ); continue; } @@ -189,6 +201,7 @@ const readDynamicTags = ( note( scan, "PT_DYNAMIC has no DT_NULL terminator. Tags seen before the end were used.", + "unknown", ); return tags; }; @@ -197,7 +210,7 @@ const readDynamicTags = ( * File offset of `size` bytes at `address`: a whole slot, or a target's first * byte. Only load mappings establish linked addresses: section declarations * cannot supply backing for an unmapped or zero-filled address. Ambiguous - * mappings stay unknown and make the report incomplete. + * mappings stay unknown and leave coverage unknown. */ const fileOffsetFor = ( scan: ElfScan, @@ -209,7 +222,7 @@ const fileOffsetFor = ( return mappings.offset(address, size); } catch (cause) { if (!(cause instanceof BinaryMappingFailure)) throw cause; - if (cause.reason === "ambiguous") note(scan, AMBIGUOUS_MAPPING); + if (cause.reason === "ambiguous") note(scan, AMBIGUOUS_MAPPING, "unknown"); return null; } }; @@ -282,6 +295,7 @@ const slotsFromSpan = ( byteSize < 0n ? `${label} size is negative.` : `${label} size is not a multiple of the pointer width. Trailing bytes were not read.`, + "partial", ); if (byteSize < 0n) return []; const declared = byteSize / stride; @@ -292,6 +306,7 @@ const slotsFromSpan = ( note( scan, `${label} declares ${declared.toString()} slots. Scanning stopped at the ${String(MAX_NATIVE_INITIALIZER_ENTRIES)}-slot budget, so later slots were not read.`, + "partial", ); const slots: ArraySlot[] = []; let missed = false; @@ -308,6 +323,7 @@ const slotsFromSpan = ( note( scan, `${label} has slots that are not file-backed. Those slots were omitted.`, + "partial", ); return slots; }; @@ -357,11 +373,16 @@ const sectionSource = ( note( scan, `${label} is compressed. Its initializer slots were not decoded.`, + "partial", ); return { kind, sentinel, detail: label, slots: [] }; } if (!section.file_backed) { - note(scan, `${label} is not file-backed. Its slots were omitted.`); + note( + scan, + `${label} is not file-backed. Its slots were omitted.`, + "partial", + ); return { kind, sentinel, detail: label, slots: [] }; } return { @@ -411,7 +432,11 @@ const arraySources = ( ); const size = tags.get(request.sizeTag); if (size === undefined) { - note(scan, `${request.detail} has no size tag. Its slots were not read.`); + note( + scan, + `${request.detail} has no size tag. Its slots were not read.`, + "partial", + ); return []; } return [ @@ -456,7 +481,11 @@ const directSource = ( const va = vaForFile(mappings, entry.valueOffset); // DT_INIT / DT_FINI store the target, not a slot pointer, so an unmapped field has no slot address. if (va === null) - note(scan, `${detail} value field is not inside a load segment.`); + note( + scan, + `${detail} value field is not inside a load segment.`, + "unknown", + ); return { kind, sentinel: false, @@ -635,12 +664,13 @@ const loadWrites = async ( note( scan, `${String(clobbered.size)} initializer slot(s) are partly overwritten or written more than once by dynamic relocations and are listed as unresolved.`, + "unknown", ); if (!next.value.pointer_coverage_known) { const issues = next.value.issues; if (issues.length === 0) - note(scan, "Dynamic relocation coverage is incomplete."); - for (const issue of issues) note(scan, issue); + note(scan, "Dynamic relocation coverage is incomplete.", "unknown"); + for (const issue of issues) note(scan, issue, "unknown"); return { writes, clobbered, trustRaw: false }; } return { writes, clobbered, trustRaw: true }; @@ -652,7 +682,7 @@ const loadWrites = async ( cause.kind === "limit" ) throw cause; - note(scan, cause.message); + note(scan, cause.message, "unknown"); return { writes: new Map(), clobbered: new Set(), trustRaw: false }; } }; @@ -718,7 +748,7 @@ const fromDynamicWrite = ( definedName: null, }; if (symbolsUnavailable && write.symbol_index !== 0) - note(scan, UNAVAILABLE_DYNAMIC_SYMBOLS); + note(scan, UNAVAILABLE_DYNAMIC_SYMBOLS, "unknown"); return relocationFromEntry( scan, { @@ -902,7 +932,7 @@ const collectEntries = ( note( scan, "A stored zero slot is listed so the array length stays visible. It is not a function address.", - false, + "complete", ); } const target = targetOf(scan, applied, sections, index, locateTarget); @@ -927,12 +957,13 @@ const collectEntries = ( note( scan, "Initializer scanning stopped at 65536 slots. Later slots were not read.", + "partial", ); if (skipped > 0) note( scan, `Omitted ${String(skipped)} .ctors or .dtors sentinel values (0 or -1).`, - false, + "complete", ); return { entries, examined: scanned }; }; @@ -953,14 +984,14 @@ export const readElfInitializers = async ( machine: image.elf.machine, relocatable: directory.elf_type === ET_REL, notes: new InitializerNotes(), - incomplete: false, + coverage: "complete", slotBudget: MAX_NATIVE_INITIALIZER_ENTRIES, }; if (scan.relocatable) note( scan, "Relocatable object (ET_REL): slot and value addresses are offsets inside the named section, not load addresses.", - false, + "complete", ); const tags = readDynamicTags( scan, @@ -969,7 +1000,7 @@ export const readElfInitializers = async ( ); const namesKnown = directory.section_names_limitation === undefined; if (!namesKnown && directory.section_names_limitation !== undefined) - note(scan, directory.section_names_limitation); + note(scan, directory.section_names_limitation, "unknown"); const index = indexSections(directory.sections); const mappings = createFileMappingIndex(image.mappings, image.zero_fills); const locate = (address: bigint): number | null => @@ -1002,6 +1033,7 @@ export const readElfInitializers = async ( note( scan, "An ELF initializer slot's section offset disagrees with its load mapping; affected slots are unresolved.", + "unknown", ); return { ...slot, mappingMismatch: true }; }), @@ -1016,7 +1048,9 @@ export const readElfInitializers = async ( const loaded = await loadWrites(scan, image, wanted, signal); assertArtifactReadActive(signal); const symbols = loadElfSymbolIndex(scan, directory.sections, scan.notes); - if (symbols.incomplete) scan.incomplete = true; + // Missing or budget-stopped symbols leave unknown which listed slots lack a name. + if (symbols.incomplete) + scan.coverage = joinCoverageStatus([scan.coverage, "unknown"]); const uncovered = sources.flatMap((source) => source.slots.flatMap((slot) => slot.direct === undefined && @@ -1039,7 +1073,7 @@ export const readElfInitializers = async ( signal, }); if (scan.notes.recorded !== notesBeforeRelocs || !sectionRels.complete) - scan.incomplete = true; + scan.coverage = joinCoverageStatus([scan.coverage, "unknown"]); const dynamic = dynamicSymbols( scan, directory.sections, @@ -1076,6 +1110,6 @@ export const readElfInitializers = async ( collected.examined, scan.notes, page, - scan.incomplete, + scan.coverage, ); }; diff --git a/src/native/initializers/MachoInitializers.ts b/src/native/initializers/MachoInitializers.ts index 6a4685bd86..950923afaa 100644 --- a/src/native/initializers/MachoInitializers.ts +++ b/src/native/initializers/MachoInitializers.ts @@ -28,6 +28,10 @@ import { type ImageSection, } from "../../domain/binaryContainer.js"; import { readMachoImage } from "../../domain/apple/machoImage.js"; +import { + joinCoverageStatus, + type CoverageStatus, +} from "../../domain/coverage.js"; import { finishInitializerReport, type CollectedInitializer, @@ -72,16 +76,26 @@ export interface MachoInitializerImage { interface MachoScan { readonly bytes: Buffer; readonly notes: InitializerNotes; - incomplete: boolean; + /** Known gaps (`partial`) and undetermined facts (`unknown`) noted so far. */ + coverage: CoverageStatus; /** Pointer slots whose fixup decode returned no rebase, bind or raw value. */ undecoded: number; /** Object-file slots whose section relocation this reader does not apply. */ unappliedObjectRelocations: number; } -const note = (scan: MachoScan, message: string): void => { +/** Widen coverage: `partial` for a known gap, `unknown` when it cannot be determined. */ +const widen = (scan: MachoScan, effect: "partial" | "unknown"): void => { + scan.coverage = joinCoverageStatus([scan.coverage, effect]); +}; + +const note = ( + scan: MachoScan, + message: string, + effect: "partial" | "unknown", +): void => { scan.notes.add(message); - scan.incomplete = true; + widen(scan, effect); }; /** @@ -111,7 +125,7 @@ const layoutFixups = async ( slice: undefined, }); if (!selected.ok) { - note(scan, selected.error.message); + note(scan, selected.error.message, "unknown"); return { fixups: null, base: null }; } try { @@ -136,6 +150,7 @@ const layoutFixups = async ( cause instanceof Error ? cause.message : "Mach-O fixups could not be decoded.", + "unknown", ); return { fixups: null, base: null }; } @@ -202,11 +217,18 @@ interface MachoSymbols { readonly table: SymbolTable | null; } -/** Name at `strx`. Index 0 is the empty name; an index outside the table is unreadable. */ +/** + * Name at `strx`. Index 0 is the empty name; an index outside the table is + * unreadable, which leaves coverage unknown. `overBudget` is the coverage + * effect of a name over the name budget: `partial` when it is the reported + * entry's own name (a known withheld fact), `unknown` when it only feeds the + * symbol index, where which entries it would have named cannot be told. + */ const nameAt = ( scan: MachoScan, strings: Buffer, strx: number, + overBudget: "partial" | "unknown", ): string | null => { if (strx === 0) return null; const observed = observeElfStringTableEntry( @@ -216,18 +238,18 @@ const nameAt = ( ); if (observed.state === "truncated") { scan.notes.tally("long-symbol-name"); - scan.incomplete = true; + widen(scan, overBudget); return null; } if (observed.state === "outside") { scan.notes.tally("unreadable-symbol-name"); - scan.incomplete = true; + widen(scan, "unknown"); return null; } const text = decodeMachoName(observed.bytes); if (typeof text !== "string") { scan.notes.tally("unreadable-symbol-name"); - scan.incomplete = true; + widen(scan, "unknown"); return null; } return text.length === 0 ? null : text; @@ -256,7 +278,7 @@ const readSymbols = ( if (frame.value.command !== LC.SYMTAB) continue; const table = readMachoSymtabCommand(body, little); if (table === null) { - note(scan, "LC_SYMTAB is truncated."); + note(scan, "LC_SYMTAB is truncated.", "unknown"); return done(); } const stringsEnd = table.stroff + table.strsize; @@ -267,7 +289,7 @@ const readSymbols = ( stringsEnd > scan.bytes.length || table.nsyms > (scan.bytes.length - table.symoff) / width ) { - note(scan, "LC_SYMTAB points outside the Mach-O image."); + note(scan, "LC_SYMTAB points outside the Mach-O image.", "unknown"); return done(); } const range = `${String(table.symoff)}:${String(table.nsyms)}:${String(table.stroff)}:${String(table.strsize)}`; @@ -307,7 +329,7 @@ const readSymbols = ( ? scan.bytes.readUInt32LE(at + 8) : scan.bytes.readUInt32BE(at + 8), ); - const text = nameAt(scan, strings, strx); + const text = nameAt(scan, strings, strx, "unknown"); if (text === null || names.has(value)) continue; names.set(value, text); } @@ -315,6 +337,7 @@ const readSymbols = ( note( scan, `Symbol scanning stopped at ${String(SYMBOL_SCAN)} symbols across all LC_SYMTAB commands. Later names may be missing.`, + "unknown", ); return done(); } @@ -421,8 +444,9 @@ const decodePointer = ( const overBudget = decoded.symbol.length > MAX_NATIVE_INITIALIZER_NAME_BYTES; if (overBudget) { + // This entry's own import name is withheld: a known gap. scan.notes.tally("long-symbol-name"); - scan.incomplete = true; + widen(scan, "partial"); } return { method: "unresolved_import", @@ -432,7 +456,7 @@ const decodePointer = ( definedName: null, }; } - note(scan, decoded.reason); + note(scan, decoded.reason, "unknown"); return { method: "unresolved", value: null, @@ -512,6 +536,7 @@ const objectRelocations = ( note( walk.scan, `${section.name} relocation entries lie outside the file, so its slots are listed as unresolved.`, + "unknown", ); return { bySlot, complete: false }; } @@ -521,6 +546,7 @@ const objectRelocations = ( note( walk.scan, `Object-file relocation scanning stopped at ${String(SECTION_RELOCATION_SCAN)} entries. Slots past that point are listed as unresolved.`, + "unknown", ); const little = walk.image.byte_order === "little"; const length = stride === 8 ? 3 : 2; @@ -605,13 +631,14 @@ const objectSymbol = ( ); // Debugger stabs never name a relocation target. if ((type & 0xe0) !== 0) return UNRESOLVED; - const name = nameAt(walk.scan, table.strings, strx); + // The name is this entry's own, so one over the budget is a withheld fact. + const ownName = () => nameAt(walk.scan, table.strings, strx, "partial"); // N_UNDF: defined in another object or library. if ((type & 0x0e) === 0) return { method: "unresolved_import", value: null, - importName: name, + importName: ownName(), definedName: null, }; // Only N_SECT has an address in this object. @@ -620,7 +647,8 @@ const objectSymbol = ( method: "symbol_addend", value: BigInt.asUintN(walk.image.bits, value + stored), importName: null, - definedName: stored === 0n ? name : null, + // A nonzero addend points past the symbol, so its name is not reported. + definedName: stored === 0n ? ownName() : null, }; }; @@ -662,6 +690,7 @@ const slotsOf = async ( note( walk.scan, `${section.name} is not file-backed. Its slots were omitted.`, + "partial", ); return false; } @@ -669,6 +698,7 @@ const slotsOf = async ( note( walk.scan, `${section.name} size is not a multiple of its slot width. Trailing bytes were not read.`, + "partial", ); const count = Math.floor(section.size / stride); const little = walk.image.byte_order === "little"; @@ -690,6 +720,7 @@ const slotsOf = async ( note( walk.scan, `${section.name} slot mapping disagrees with its section offset; affected slots are unresolved.`, + "unknown", ); const unresolved: SlotRelocation = { method: "unresolved", @@ -793,7 +824,7 @@ export const readMachoInitializers = async ( const scan: MachoScan = { bytes: image.bytes, notes: new InitializerNotes(), - incomplete: false, + coverage: "complete", undecoded: 0, unappliedObjectRelocations: 0, }; @@ -833,6 +864,7 @@ export const readMachoInitializers = async ( note( scan, "An address has ambiguous file mappings (overlapping load segments with different file offsets, or file and zero-fill memory), so its file offset is not reported.", + "unknown", ); return null; } @@ -874,23 +906,27 @@ export const readMachoInitializers = async ( note( scan, "Initializer scanning stopped at 65536 slots. Later slots were not read.", + "partial", ); // decode() records failures lazily, so sample them only after every slot was decoded. if ( container.macho_chained_fixups === true && (decoded.fixups === null || decoded.fixups.failures.length > 0) ) - note(scan, "Mach-O chained fixup coverage is incomplete."); - if (unchecked !== null && scan.undecoded > 0) note(scan, unchecked); + note(scan, "Mach-O chained fixup coverage is incomplete.", "unknown"); + if (unchecked !== null && scan.undecoded > 0) + note(scan, unchecked, "unknown"); if (scan.unappliedObjectRelocations > 0) note( scan, `${String(scan.unappliedObjectRelocations)} object-file slot(s) have section relocations this reader does not apply and are listed as unresolved.`, + "unknown", ); if (scan.undecoded > 0) note( scan, `${String(scan.undecoded)} pointer slot(s) could not be decoded through Mach-O fixups and are listed as unresolved.`, + "unknown", ); return finishInitializerReport( { @@ -907,6 +943,6 @@ export const readMachoInitializers = async ( entries.length, scan.notes, page, - scan.incomplete, + scan.coverage, ); }; diff --git a/src/native/initializers/NativeInitializersParsers.test.ts b/src/native/initializers/NativeInitializersParsers.test.ts index 9fbf6915f7..6329cd821b 100644 --- a/src/native/initializers/NativeInitializersParsers.test.ts +++ b/src/native/initializers/NativeInitializersParsers.test.ts @@ -403,10 +403,10 @@ describe("ELF slot semantics", () => { expect(report.limitations.join("\n")).not.toContain("DT_SYMTAB"); }); - it("marks coverage incomplete when a relocation needs the missing DT_SYMTAB", async () => { + it("leaves coverage unknown when a relocation needs the missing DT_SYMTAB", async () => { const report = await read(sectionlessElf(false)); expect(report.coverage).toMatchObject({ - status: "incomplete", + status: "unknown", total_entries: null, }); expect(report.limitations).toContain( @@ -543,7 +543,7 @@ describe("ELF incomplete inputs", () => { expect(performance.now() - started).toBeLessThan(10_000); expect(report.status).toBe("incomplete"); expect(report.coverage).toMatchObject({ - status: "incomplete", + status: "partial", total_entries: null, }); expect(report.coverage.examined_entries).toBeLessThanOrEqual( @@ -564,7 +564,7 @@ describe("ELF incomplete inputs", () => { const report = await read(bytes); expect(report.status).toBe("incomplete"); expect(report.coverage).toMatchObject({ - status: "incomplete", + status: "partial", examined_entries: MAX_NATIVE_INITIALIZER_ENTRIES, total_entries: null, }); @@ -617,7 +617,7 @@ describe("ELF incomplete inputs", () => { const beyond = await read(bytes, { offset: 100 }); expect(beyond.entries).toHaveLength(0); expect(beyond.status).toBe("incomplete"); - expect(beyond.coverage.status).toBe("incomplete"); + expect(beyond.coverage.status).toBe("partial"); expect( beyond.limitations.some((line) => line.includes("exceeded the 1024-byte name budget"), @@ -770,7 +770,7 @@ describe("Mach-O", () => { }); expect(report.status).toBe("incomplete"); expect(report.coverage).toMatchObject({ - status: "incomplete", + status: "unknown", total_entries: null, }); expect(report.limitations).toEqual( @@ -1622,6 +1622,32 @@ describe("Mach-O fixup sources", () => { }); }); +it("reports an object-file import name over the name budget as partial coverage", async () => { + const fixture = machoX8664ObjectInitializers(); + // `_startup` (nlist 2) becomes an undefined external with a 1101-byte name. + const strings = Buffer.from(`\0_before\0_${"s".repeat(1100)}\0`, "utf8"); + const image = Buffer.alloc(0x270 + strings.length); + fixture.copy(image, 0, 0, 0x270); + strings.copy(image, 0x270); + image.writeUInt32LE(strings.length, 284); + image.writeUInt8(0x01, 0x260 + 4); + image.writeUInt8(0, 0x260 + 5); + const report = await read(image); + expect(report.entries[0]).toMatchObject({ + resolution: "unresolved_import", + symbol: null, + }); + expect(report.status).toBe("incomplete"); + // The withheld name is this entry's own: a known gap, not unknown coverage. + expect(report.coverage).toMatchObject({ + status: "partial", + total_entries: null, + }); + expect(report.limitations).toContain( + "1 symbol name(s) exceeded the 1024-byte name budget and were not used.", + ); +}); + describe("Initializer target semantics", () => { it("keeps an absolute relocation against an IFUNC symbol unresolved", async () => { const bytes = elfRelocatableCtors(); @@ -1898,7 +1924,7 @@ describe("Initializer address mapping", () => { expect(many.indexes).toBeGreaterThan(0); }); - it("reports a Mach-O bind name over the name budget as incomplete", async () => { + it("reports a Mach-O bind name over the name budget as partial coverage", async () => { const bytes = machoArm64Initializers(); const name = `_${"b".repeat(1100)}`; // Rebuild the chained-fixups payload with one DYLD_CHAINED_IMPORT bound by flat lookup. @@ -1927,6 +1953,11 @@ describe("Initializer address mapping", () => { symbol: null, }); expect(report.status).toBe("incomplete"); + // The withheld import name is a known gap, not undetermined coverage. + expect(report.coverage).toMatchObject({ + status: "partial", + total_entries: null, + }); expect(report.limitations).toContain( "1 symbol name(s) exceeded the 1024-byte name budget and were not used.", ); @@ -1942,7 +1973,7 @@ it("keeps a slot touched by an overrun section relocation unresolved", async () offset: 0, limit: 64, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect( report.entries.find((entry) => entry.kind === "init_array"), ).toMatchObject({ resolution: "unresolved", value_va: null }); @@ -1970,7 +2001,7 @@ it("retains unknown coverage when sparse bind lookups exhaust their allowance", offset: 0, limit: 1, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect(report.entries[0]).toMatchObject({ resolution: "unresolved", value_va: null, @@ -2007,7 +2038,7 @@ it("keeps a linked section-fallback slot unresolved when its load mapping disagr offset: 0, limit: 64, }); - expect(report.coverage.status).toBe("incomplete"); + expect(report.coverage.status).toBe("unknown"); expect( report.entries.find((entry) => entry.kind === "init_array"), ).toMatchObject({ diff --git a/src/native/initializers/initializerReport.ts b/src/native/initializers/initializerReport.ts index e17ed5c29a..3793270cd8 100644 --- a/src/native/initializers/initializerReport.ts +++ b/src/native/initializers/initializerReport.ts @@ -11,6 +11,10 @@ import { NATIVE_INITIALIZER_LIMITATIONS, } from "../../domain/native/nativeInitializers.js"; import type { InitializerNotes } from "./initializerNotes.js"; +import { + joinCoverageStatus, + type CoverageStatus, +} from "../../domain/coverage.js"; /** Page requested by the caller after schema defaults. */ export interface InitializerPage { @@ -51,7 +55,7 @@ const pageOf = ( entries: readonly CollectedInitializer[], examined: number, page: InitializerPage, - incomplete: boolean, + status: CoverageStatus, ): { readonly entries: CollectedInitializer[]; readonly coverage: NativeInitializerCoverage; @@ -60,9 +64,9 @@ const pageOf = ( return { entries: returned, coverage: { - status: incomplete ? "incomplete" : "complete", + status, examined_entries: examined, - total_entries: incomplete ? null : entries.length, + total_entries: status === "complete" ? entries.length : null, returned_entries: returned.length, offset: page.offset, limit: page.limit, @@ -88,7 +92,9 @@ const toEntry = (entry: CollectedInitializer): NativeInitializerEntry => ({ /** * Standing limitations first, then observations from this image. `examined` - * counts every slot read, including omitted sentinels. + * counts every slot read, including omitted sentinels. `coverage` is the + * scan's own: `partial` when it left declared slots or names unreported, + * `unknown` when it could not determine whether the listed facts are complete. */ export const finishInitializerReport = ( body: Omit< @@ -99,7 +105,7 @@ export const finishInitializerReport = ( examined: number, notes: InitializerNotes, page: InitializerPage, - incomplete: boolean, + coverage: CoverageStatus, ): NativeInitializerInspection => { let withheld = 0; for (const entry of entries) @@ -111,13 +117,17 @@ export const finishInitializerReport = ( ]) if (name !== null && name.length > MAX_NATIVE_INITIALIZER_NAME_BYTES) withheld += 1; - const incompleteReport = incomplete || withheld > 0; - const paged = pageOf(entries, examined, page, incompleteReport); + // A withheld name is a known gap in this entry's reported facts. + const status = joinCoverageStatus([ + coverage, + withheld > 0 ? "partial" : "complete", + ]); + const paged = pageOf(entries, examined, page, status); const returned = paged.entries.map(toEntry); return { ...body, applicability: "applicable", - status: incompleteReport ? "incomplete" : "parsed", + status: status === "complete" ? "parsed" : "incomplete", coverage: paged.coverage, entries: returned, limitations: [