Files
reverse-engineering-anything/docs/specs/native/dwarf-units/plan.md
T
Matt Van Hornandgensokyo-dev 637e4cb60c feat(native): inspect DWARF compile units offline
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>
2026-11-17 10:04:46 +00:00

47 lines
2.3 KiB
Markdown

# 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
1. Define the domain schema, limits, coverage states and MCP/CLI contracts.
2. Implement section location and decompression, abbreviation decoding, the
bounded reader and the unit parser with synthetic fixtures for each form,
version and failure path.
3. Wire the provider, service, composition, capability inventory and server
registration; add boundary, MCP and CLI acceptance tests.
4. Add `scripts/verify-dwarf-units.mjs` to compare compiled fixtures with
`llvm-dwarfdump`, and record the run.
5. Add the [DWARF compile units guide](../../../guides/native/dwarf-units.md),
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.