Add bounded offline DWARF compilation-unit inspection with source provenance, explicit coverage, caller-selected controls and shared ELF compression framing. Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning) Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2.3 KiB
Implementation plan
Boundary and contract
Define the report in src/domain/native/dwarfUnits.ts: artifact identity,
container format, byte order and architecture, sections with stored name,
file offset, stored size and compression, omissions, the requested units
page with per-attribute state and issues, total_units and coverage.
Schema refinements tie attribute state to value presence and require a reason
for partial coverage. Add the MCP contract in
src/contracts/native/binaryDiagnosticsToolContracts.ts and the CLI command in
src/cli/binaryDiagnosticsCommands.ts, registered in the existing binary
diagnostics group.
Parse in src/native/dwarf/: DwarfSections locates and decompresses debug
sections through BinaryContainer, DwarfAbbrev decodes abbreviation tables
under a shared work budget, DwarfReader is the bounded cursor,
DwarfUnitParser frames units and reads the unit DIE, and DwarfUnitsProvider
assembles the report. DwarfUnitsService in src/application/binaryDiagnostics/
reads the selected path through the stable artifact read.
Shared changes stay with their owners: ElfCompressedSection.ts and
ElfSectionNameTable.ts for section decoding, MachoImage.ts and
BinaryContainer.ts for an on_disk section fact so an unmapped Mach-O
__DWARF segment is read by file range, and artifactOperationError.ts for a
typed allowance failure.
Incremental work and validation
- Define the domain schema, limits, coverage states and MCP/CLI contracts.
- Implement section location and decompression, abbreviation decoding, the bounded reader and the unit parser with synthetic fixtures for each form, version and failure path.
- Wire the provider, service, composition, capability inventory and server registration; add boundary, MCP and CLI acceptance tests.
- Add
scripts/verify-dwarf-units.mjsto compare compiled fixtures withllvm-dwarfdump, and record the run. - Add the DWARF compile units guide, CLI guide entry, README rows and skill guidance; run documentation checks.
Effects and compatibility
The tool is additive and read-only over one local file. No provider, bridge or
external tool runs at inspection time, the target is never executed, and no
resources are retained. Existing readers keep their output; the on_disk
section fact is additive.