[GH-ISSUE #2377] [Feature] Inspect JVM source-line and local-variable metadata for debugging readiness #789

New issue

Open

opened 2026-10-15 18:28:21 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:28:21 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2377

Analyst question

Before attaching a debugger, does my selected class file contain enough original debug metadata to associate bytecode locations and local slots with source?

This is a focused child capability of #1558 and a static foundation for JVM debugging. Decompiled line numbers are not compiler-emitted source positions.

Desired behavior

Inspect SourceFile, SourceDebugExtension, LineNumberTable, LocalVariableTable and LocalVariableTypeTable on caller-selected .class/JAR artifacts.
Bind method name plus descriptor, bytecode offset, local slot and scope range to exact class/member artifact identity.
Preserve raw source paths and debug-extension data with bounded access. Interpret an admitted source-map dialect only when established; unknown extensions remain opaque.
Distinguish absent tables, malformed records, partial examination and ambiguous mappings. Reused local slots can denote different variables across scope ranges.
In a multi-release JAR, select the requested effective class version explicitly or report alternatives; never silently combine metadata from different entries.
Return shared CLI/MCP facts and deterministic ordering without executing Java, resolving source URLs or claiming that supplied source bytes match a SourceFile name.

Acceptance

Owned javac fixtures compiled with full debug metadata and -g:none show the actual difference.
Tests cover overloads, slot reuse, wide locals, duplicate line entries, invalid ranges and truncated attributes.
Multi-release archive tests bind facts to the selected exact member.
SourceDebugExtension tests separate opaque extension preservation from any verified mapping interpretation.
Debug metadata identity remains separate from derived decompiler output.
A single spec/plan under docs/specs/-jvm-debug-metadata/ defines format limits and contracts.

References and dependencies

Java domain: #1558; JVM runtime proposal is a separate feature.
JVMS class-file attributes, sections 4.7.10–4.7.14

Originally created by @matbrgz on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2377 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Analyst question Before attaching a debugger, does my selected class file contain enough original debug metadata to associate bytecode locations and local slots with source? This is a focused child capability of #1558 and a static foundation for JVM debugging. Decompiled line numbers are not compiler-emitted source positions. ## Desired behavior - Inspect SourceFile, SourceDebugExtension, LineNumberTable, LocalVariableTable and LocalVariableTypeTable on caller-selected .class/JAR artifacts. - Bind method name plus descriptor, bytecode offset, local slot and scope range to exact class/member artifact identity. - Preserve raw source paths and debug-extension data with bounded access. Interpret an admitted source-map dialect only when established; unknown extensions remain opaque. - Distinguish absent tables, malformed records, partial examination and ambiguous mappings. Reused local slots can denote different variables across scope ranges. - In a multi-release JAR, select the requested effective class version explicitly or report alternatives; never silently combine metadata from different entries. - Return shared CLI/MCP facts and deterministic ordering without executing Java, resolving source URLs or claiming that supplied source bytes match a SourceFile name. ## Acceptance - [ ] Owned javac fixtures compiled with full debug metadata and -g:none show the actual difference. - [ ] Tests cover overloads, slot reuse, wide locals, duplicate line entries, invalid ranges and truncated attributes. - [ ] Multi-release archive tests bind facts to the selected exact member. - [ ] SourceDebugExtension tests separate opaque extension preservation from any verified mapping interpretation. - [ ] Debug metadata identity remains separate from derived decompiler output. - [ ] A single spec/plan under docs/specs/<NNN>-jvm-debug-metadata/ defines format limits and contracts. ## References and dependencies - Java domain: #1558; JVM runtime proposal is a separate feature. - [JVMS class-file attributes, sections 4.7.10–4.7.14](https://docs.oracle.com/javase/specs/jvms/se25/html/jvms-4.html)

bsakaguchi added the

area: domain

enhancement

P2: medium

labels

2026-10-15 18:28:21 +00:00

bsakaguchi commented

2026-10-15 18:28:23 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

Implementation & Triage Notes

Objective (ELI5):
Read JVM .class bytecode attributes (LineNumberTable, LocalVariableTable, and LocalVariableTypeTable) to assess whether a compiled artifact is equipped for full source-level debugging.

Verification Criteria:

Detect stripped vs debug builds: emit debug_metadata: "present" | "stripped" | "partial" based on attributes found in method structures.
Obfuscated classes (e.g., ProGuard/R8) with scrambled variable tables must be identified with obfuscation_suspected: true.
Related to #2317 / PR #2405 for proper class file artifact recognition.

@matbrgz commented on GitHub (Oct 12, 2026): ### Implementation & Triage Notes **Objective (ELI5):** Read JVM `.class` bytecode attributes (`LineNumberTable`, `LocalVariableTable`, and `LocalVariableTypeTable`) to assess whether a compiled artifact is equipped for full source-level debugging. **Verification Criteria:** - Detect stripped vs debug builds: emit `debug_metadata: "present" | "stripped" | "partial"` based on attributes found in method structures. - Obfuscated classes (e.g., ProGuard/R8) with scrambled variable tables must be identified with `obfuscation_suspected: true`. - Related to #2317 / PR #2405 for proper class file artifact recognition.

bsakaguchi referenced this issue

2026-10-16 21:16:09 +00:00

[PR #789] [CLOSED] fix(reference): preserve unsupported import failures #2240

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:29:37 +00:00

bsakaguchi referenced this issue

2026-10-31 00:38:36 +00:00

[GH-ISSUE #5399] [Bug] Reference-source import root errors omit required machine-readable fields #3269