morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #6968] [CLOSED] fix(android): resolve exact DEX binary class names #7482

New issue

Closed

opened 2026-11-01 21:48:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:48:08 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6968
Author: @AliAkbariAlashti
Created: 10/24/2026
Status: ❌ Closed

Base: main ← Head: fix/android-binary-class-names

📝 Commits (1)

0196c0e fix(android): resolve exact DEX binary class names

📊 Changes

11 files changed (+113 additions, -9 deletions)

View changed files

📝 bridge/android/ReaJadxBridge.java (+11 -4)
📝 docs/android-analysis.md (+5 -1)
📝 scripts/verify/android/metadata.mjs (+7 -0)
📝 src/android/JadxAnalysis.ts (+4 -1)
📝 src/android/JadxProtocol.ts (+1 -0)
📝 src/android/JadxRelease.ts (+1 -1)
📝 src/cli/androidCommands.ts (+5 -1)
📝 src/domain/android/androidAnalysis.ts (+6 -1)
📝 tests/boundary/android/JadxAnalysis.test.ts (+43 -0)
📝 tests/conformance/android/ReaJadxMetadataRegression.java (+29 -0)
📝 tests/fixtures/android/jadx-mcp.mjs (+1 -0)

📄 Description

Summary

inspect_android_class, inspect_android_method and trace_android_references refused valid DEX binary class names such as Outer$Inner and Outer$1 with invalid_request, although JADX knows those classes. They now resolve when the caller passes the exact DEX binary name or the exact displayed name.

Fixes #6398

Problem and expected behavior

Trigger, against the real ApiDemos fixture with jadx-headless-mcp 0.7.1:

rea inspect-android-method ApiDemos-debug.apk 'io.appium.android.apis.app.FragmentArguments$MyFragment' onCreate --format json
# invalid_request: Exact class not found: io.appium.android.apis.app.FragmentArguments$MyFragment; ...

The dotted form FragmentArguments.MyFragment succeeded. On d87e73f the refusal already names class_name with a reason, so the "no details" part of the issue is fixed. The $ refusal remained.

Cause: ReaJadxBridge.selected indexed classes only by JADX's displayed getFullName(). JADX rewrites nested and anonymous names (AlertDialogSamples$1 → AlertDialogSamples.AnonymousClass1), so the adapter cannot derive one form from the other by replacing $ with ..

Change and scope

The bridge, which owns class identity, indexes each frozen class snapshot under its exact displayed name and its exact ClassNode.getRawName(). It adds the raw-name key only when the two names differ. A key shared by distinct classes still reaches the existing Ambiguous metadata class identity refusal.
The class summary reports raw_name. The bridge protocol is bumped from 5 to 6 for the new field.
JadxAnalysis accepts the summary when the request equals full_name or raw_name. Later calls keep using the displayed full_name, and results still report the displayed name.
The class_name CLI/MCP descriptions and docs/android-analysis.md state that binary names are accepted.

Not included: suffix, nesting-insensitive or simple-name matching. Upstream resolve_class does these, but they would weaken the exact-identity contract. Also not included: adding raw_name to public results, and listing inner classes in search_android_classes.

Contribution scope: not applicable. This is an ordinary fix within the existing read-only static Android boundary.

Contract and boundary impact

Semantic owner and earliest changed stage: ReaJadxBridge.selected (class identity index), then the JadxAnalysis.classSummary identity check.
Contribution scope fit and linked maintainer decision: existing static Android provider; no new authority.
CLI and MCP/tool-catalog contract: class_name description text changes; the schema type is unchanged. Inputs refused before are now accepted. Result shape is unchanged.
Provider, bridge, target-format, or platform compatibility: bridge protocol 5 → 6 (new raw_name summary field). Pinned engine stays jadx-headless-mcp 0.7.1.
Evidence, artifact, provenance, or reconstruction contract: unchanged. Evidence parameters.class_name keeps the caller's input, and normalized_result.class_name reports JADX's displayed name.
Target selection, authority, upstream behavior, and cleanup details: unchanged.
Generated metadata, package, or installation impact: the catalog description for class_name changes when regenerated.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated:
- tests/conformance/android/ReaJadxMetadataRegression.java: a real-JAR regression. A named inner class and an anonymous class each resolve by binary name to the same frozen summary as their displayed name. An absent binary name is refused. Asserted by scripts/verify/android/metadata.mjs (BINARY_CLASS_NAME_REGRESSION_PASS).
- tests/boundary/android/JadxAnalysis.test.ts: the adapter accepts an exact displayed or raw identity and refuses fixture.Outer.1, which matches neither.
- Protocol fixtures now carry raw_name.
Base reproduction (executed on d87e73f, real JADX): FragmentArguments$MyFragment and AlertDialogSamples$1 both returned invalid_request / Exact class not found. The new Java regression would fail on base at the first get_class_summary call by binary name.

User-visible CLI output after the change (real JADX, ApiDemos):

FragmentArguments$MyFragment onCreate => ok class=io.appium.android.apis.app.FragmentArguments.MyFragment body=available
FragmentArguments.MyFragment onCreate => ok class=io.appium.android.apis.app.FragmentArguments.MyFragment body=available
AlertDialogSamples$1 onClick          => ok class=io.appium.android.apis.app.AlertDialogSamples.AnonymousClass1 body=available
FragmentArguments$Nope onCreate       => invalid_request: Exact class not found: io.appium.android.apis.app.FragmentArguments$Nope; ...

Remaining proof gaps: the verify:android failure-recovery stage did not run because the host JDK has no jlink. That stage covers JVM failure recovery, not class identity. Windows and macOS were not exercised. A real name collision between distinct classes was not constructed; that path reuses the existing ambiguity refusal.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run test:focused -- <21 Android-related test files>: 21 files, 254 tests passed.
REA_JADX_MCP_JAR=… REA_ANDROID_TEST_APK=… npm run verify:android (Linux x64, OpenJDK 21.0.11, jadx-headless-mcp 0.7.1, pinned ApiDemos). These stages passed:
- real metadata regressions, including the new binary-name regression
- CLI tasks and MCP/CLI parity for all five Android operations
- overloaded references, native class search, and CLI SIGTERM cleanup
The run then stopped at failure recovery with "requires the full JDK's jlink". On unmodified main the same lane passed the metadata stages; its CLI search_android_classes hit a bridge startup handshake timeout, which did not recur on the fixed run.
Public CLI inspect-android-method with real JADX: output shown above.
npm run check:fast: typecheck and lint passed.
npm run docs:check: passed.

Compatibility, safety, and release

Breaking changes or migration steps: none. Previously refused inputs are now accepted; previously accepted inputs behave the same, except where a displayed name is also another class's raw name. That case is now refused as ambiguous instead of silently selecting one class.
Real Hopper/Ghidra, browser, or OS coverage: real JADX on Linux x64 only.
Package or release metadata impact: bridge protocol version 6.
Security, privacy, process, or containment review: no new process, file, or network behavior. The APK is never executed.

Author readiness

Human owner: @AliAkbariAlashti

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/6968 **Author:** [@AliAkbariAlashti](https://github.com/AliAkbariAlashti) **Created:** 10/24/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/android-binary-class-names` --- ### 📝 Commits (1) - [`0196c0e`](https://github.com/morluto/rea/commit/0196c0e5f4bb5e8c45a1417bdb204aae869e3cc0) fix(android): resolve exact DEX binary class names ### 📊 Changes **11 files changed** (+113 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `bridge/android/ReaJadxBridge.java` (+11 -4) 📝 `docs/android-analysis.md` (+5 -1) 📝 `scripts/verify/android/metadata.mjs` (+7 -0) 📝 `src/android/JadxAnalysis.ts` (+4 -1) 📝 `src/android/JadxProtocol.ts` (+1 -0) 📝 `src/android/JadxRelease.ts` (+1 -1) 📝 `src/cli/androidCommands.ts` (+5 -1) 📝 `src/domain/android/androidAnalysis.ts` (+6 -1) 📝 `tests/boundary/android/JadxAnalysis.test.ts` (+43 -0) 📝 `tests/conformance/android/ReaJadxMetadataRegression.java` (+29 -0) 📝 `tests/fixtures/android/jadx-mcp.mjs` (+1 -0) </details> ### 📄 Description ## Summary `inspect_android_class`, `inspect_android_method` and `trace_android_references` refused valid DEX binary class names such as `Outer$Inner` and `Outer$1` with `invalid_request`, although JADX knows those classes. They now resolve when the caller passes the exact DEX binary name or the exact displayed name. Fixes #6398 ## Problem and expected behavior Trigger, against the real ApiDemos fixture with jadx-headless-mcp 0.7.1: ```sh rea inspect-android-method ApiDemos-debug.apk 'io.appium.android.apis.app.FragmentArguments$MyFragment' onCreate --format json # invalid_request: Exact class not found: io.appium.android.apis.app.FragmentArguments$MyFragment; ... ``` The dotted form `FragmentArguments.MyFragment` succeeded. On `d87e73f` the refusal already names `class_name` with a reason, so the "no details" part of the issue is fixed. The `$` refusal remained. Cause: `ReaJadxBridge.selected` indexed classes only by JADX's displayed `getFullName()`. JADX rewrites nested and anonymous names (`AlertDialogSamples$1` → `AlertDialogSamples.AnonymousClass1`), so the adapter cannot derive one form from the other by replacing `$` with `.`. ## Change and scope - The bridge, which owns class identity, indexes each frozen class snapshot under its exact displayed name and its exact `ClassNode.getRawName()`. It adds the raw-name key only when the two names differ. A key shared by distinct classes still reaches the existing `Ambiguous metadata class identity` refusal. - The class summary reports `raw_name`. The bridge protocol is bumped from 5 to 6 for the new field. - `JadxAnalysis` accepts the summary when the request equals `full_name` or `raw_name`. Later calls keep using the displayed `full_name`, and results still report the displayed name. - The `class_name` CLI/MCP descriptions and `docs/android-analysis.md` state that binary names are accepted. Not included: suffix, nesting-insensitive or simple-name matching. Upstream `resolve_class` does these, but they would weaken the exact-identity contract. Also not included: adding `raw_name` to public results, and listing inner classes in `search_android_classes`. Contribution scope: not applicable. This is an ordinary fix within the existing read-only static Android boundary. ## Contract and boundary impact - Semantic owner and earliest changed stage: `ReaJadxBridge.selected` (class identity index), then the `JadxAnalysis.classSummary` identity check. - Contribution scope fit and linked maintainer decision: existing static Android provider; no new authority. - CLI and MCP/tool-catalog contract: `class_name` description text changes; the schema type is unchanged. Inputs refused before are now accepted. Result shape is unchanged. - Provider, bridge, target-format, or platform compatibility: bridge protocol 5 → 6 (new `raw_name` summary field). Pinned engine stays jadx-headless-mcp 0.7.1. - Evidence, artifact, provenance, or reconstruction contract: unchanged. Evidence `parameters.class_name` keeps the caller's input, and `normalized_result.class_name` reports JADX's displayed name. - Target selection, authority, upstream behavior, and cleanup details: unchanged. - Generated metadata, package, or installation impact: the catalog description for `class_name` changes when regenerated. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `tests/conformance/android/ReaJadxMetadataRegression.java`: a real-JAR regression. A named inner class and an anonymous class each resolve by binary name to the same frozen summary as their displayed name. An absent binary name is refused. Asserted by `scripts/verify/android/metadata.mjs` (`BINARY_CLASS_NAME_REGRESSION_PASS`). - `tests/boundary/android/JadxAnalysis.test.ts`: the adapter accepts an exact displayed or raw identity and refuses `fixture.Outer.1`, which matches neither. - Protocol fixtures now carry `raw_name`. - Base reproduction (executed on `d87e73f`, real JADX): `FragmentArguments$MyFragment` and `AlertDialogSamples$1` both returned `invalid_request` / `Exact class not found`. The new Java regression would fail on base at the first `get_class_summary` call by binary name. - User-visible CLI output after the change (real JADX, ApiDemos): ```text FragmentArguments$MyFragment onCreate => ok class=io.appium.android.apis.app.FragmentArguments.MyFragment body=available FragmentArguments.MyFragment onCreate => ok class=io.appium.android.apis.app.FragmentArguments.MyFragment body=available AlertDialogSamples$1 onClick => ok class=io.appium.android.apis.app.AlertDialogSamples.AnonymousClass1 body=available FragmentArguments$Nope onCreate => invalid_request: Exact class not found: io.appium.android.apis.app.FragmentArguments$Nope; ... ``` - Remaining proof gaps: the `verify:android` failure-recovery stage did not run because the host JDK has no `jlink`. That stage covers JVM failure recovery, not class identity. Windows and macOS were not exercised. A real name collision between distinct classes was not constructed; that path reuses the existing ambiguity refusal. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run test:focused -- <21 Android-related test files>`: 21 files, 254 tests passed. - `REA_JADX_MCP_JAR=… REA_ANDROID_TEST_APK=… npm run verify:android` (Linux x64, OpenJDK 21.0.11, jadx-headless-mcp 0.7.1, pinned ApiDemos). These stages passed: - real metadata regressions, including the new binary-name regression - CLI tasks and MCP/CLI parity for all five Android operations - overloaded references, native class search, and CLI SIGTERM cleanup The run then stopped at failure recovery with "requires the full JDK's jlink". On unmodified `main` the same lane passed the metadata stages; its CLI `search_android_classes` hit a bridge startup handshake timeout, which did not recur on the fixed run. - Public CLI `inspect-android-method` with real JADX: output shown above. - `npm run check:fast`: typecheck and lint passed. - `npm run docs:check`: passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Previously refused inputs are now accepted; previously accepted inputs behave the same, except where a displayed name is also another class's raw name. That case is now refused as ambiguous instead of silently selecting one class. - Real Hopper/Ghidra, browser, or OS coverage: real JADX on Linux x64 only. - Package or release metadata impact: bridge protocol version 6. - Security, privacy, process, or containment review: no new process, file, or network behavior. The APK is never executed. ## Author readiness Human owner: @AliAkbariAlashti - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:48:08 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7482

No description provided.

Rows
Columns