morluto/rea

Fork 0

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

[PR #7137] [CLOSED] feat(android): annotate class and method inspection with R8/ProGuard mappings #7667

New issue

Closed

opened 2026-11-03 13:39:29 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:39:29 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7137
Author: @555aaditya
Created: 10/25/2026
Status: ❌ Closed

Base: main ← Head: feat/proguard-mapping

📝 Commits (4)

00ea4aa feat(android): annotate class and method inspection with caller-selected R8/ProGuard mappings
9ccccac fix(android): keep same-range overloads, serialize mapping reads and index method records
d41c1c6 Merge remote-tracking branch 'origin/main' into tmp/ci-repro
505b95e fix(android): read mappings under the operation deadline and keep idle retirement

📊 Changes

26 files changed (+2228 additions, -88 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/android-applications.md (+6 -0)
📝 bridge/android/ReaJadxBridge.java (+9 -4)
📝 docs/android-analysis.md (+53 -0)
📝 docs/testing.md (+3 -3)
📝 scripts/verify/android/metadata.mjs (+4 -0)
➕ src/android/AndroidMappingFile.ts (+181 -0)
📝 src/android/JadxAnalysis.ts (+75 -5)
📝 src/android/JadxProtocol.ts (+8 -2)
📝 src/android/JadxProvider.ts (+48 -4)
📝 src/android/JadxRelease.ts (+1 -1)
📝 src/android/JadxSession.ts (+17 -3)
📝 src/cli/androidCommands.ts (+13 -1)
📝 src/contracts/android/androidToolContracts.ts (+10 -2)
📝 src/domain/android/androidAnalysis.ts (+17 -8)
➕ src/domain/android/androidMapping.ts (+243 -0)
➕ src/domain/android/dexTypes.ts (+13 -0)
➕ src/domain/android/proguardMapping.test.ts (+353 -0)
➕ src/domain/android/proguardMapping.ts (+549 -0)
📝 tests/acceptance/tools/localToolContracts.test.ts (+13 -0)
📝 tests/boundary/android/JadxAnalysis.test.ts (+322 -54)

...and 6 more files

📄 Description

Summary

Refs #6329. This is the first of two PRs: it covers class and method inspection. Search and trace come in the follow-up, so the issue stays open.

inspect_android_class and inspect_android_method (and rea inspect-android-class / inspect-android-method --mapping-path) accept an optional absolute mapping_path to an R8/ProGuard mapping.txt.

The result gains one additive mapping block:

the file's path, SHA-256 and size;
header facts the file reports: compiler, compiler_version, min_api, map_version, pg_map_id, pg_map_hash;
valid record counts and up to 16 malformed-line samples;
a resolution for each observed class, inner class, method and field;
coverage counts by status.

Observed rows, selectors and Evidence for calls without a mapping are unchanged. Mapped names are reported as claims from the file, never as observations of the APK.

Problem and expected behavior

R8/ProGuard release APKs show names like a.b.c(). An analyst who has the build's mapping.txt currently has to translate every class and member by hand.

Expected behavior: look names up by raw DEX identity, not JADX display aliases, and never guess. Each symbol resolves to one of three statuses:

Status	When
`mapped`	Exactly one record matches. Classes verify by raw name (`verified_by: "class"`), methods by DEX prototype (`"descriptor"`), fields by DEX type (`"type"`). R8 `residualsignature` metadata is used when present; otherwise original types are translated through the file's class records.
`ambiguous`	The reason is `multiple-records`, `descriptor-mismatch`, `type-mismatch` or `ambiguous-class`, with `candidate_count` and up to 8 candidates. A name-only match whose prototype or type doesn't verify is never reported as mapped.
`unmapped`	No valid record matches the raw identity.

Further behaviour:

Inline frames: a line continues a stack when it repeats the previous line's minified range and obfuscated name and gives a single call-site line (:7), as R8 writes caller frames. Only the outermost original becomes a candidate. Original line numbers and source files aren't projected.
Malformed records are counted and skipped, and parsing continues.
Refused with an input error, before JADX is touched:
- a file that is missing;
- one that is not a regular file;
- one that is not UTF-8;
- one larger than 64 MiB (resource_constraint);
- one with no class records at all, such as usage.txt or seeds.txt passed by mistake.
So a bad mapping never launches or retires the JADX session, and switching to a different mapping reuses the loaded APK.

Change and scope

Domain (pure):
- src/domain/android/proguardMapping.ts: line grammar, inline-frame grouping, residual-signature metadata, malformed samples.
- src/domain/android/androidMapping.ts: limits, the result schema and projectAndroidMapping.
- src/domain/android/dexTypes.ts: holds dexDescriptorSchema and the new dexTypeSchema, so the mapping schema can share them without a circular import.
Provider:
- src/android/AndroidMappingFile.ts reads the file through the provider's #prerequisites resource scope.
- JadxProvider reads the mapping inside the request's queue turn and under the operation deadline, before any session work. Only one parsed mapping is held at a time. A refused mapping keeps the loaded session, and its idle timer is rescheduled.
- JadxAnalysis resolves against the bridge's raw identities. It checks that the display and raw inner-class lists line up, and fails with AnalysisOutputError otherwise.
- The JADX session cache key is unchanged.
Bridge (additive, version 7 → 8): bridge/android/ReaJadxBridge.java adds:
- raw_name on methods;
- raw_name and dex_type on fields (TypeGen.signature of the raw field type);
- inner_class_raw_names on the class summary.
JadxProtocol, the Java metadata regression and scripts/verify/android/metadata.mjs are updated to match, following the shape of #6981.
Contracts and CLI:
- optional mapping_path on the two tools, with an example;
- one added sentence in each of the two tool descriptions;
- the CLI --mapping-path option.
Docs:
- docs/android-analysis.md: a new "Apply an R8/ProGuard mapping" section, the interpretation note and the memory bound;
- docs/testing.md;
- the reverse-engineering skill's Android reference.

Limits are fixed, with no runtime override (see #6176):

64 MiB per mapping file;
16 malformed samples;
8 candidates per ambiguous symbol.

The file is read once per call and parsed in memory, with no caching.

Not included:

search_android_classes and trace_android_references (PR 2).
Selecting classes or methods by mapped name.
Checking that a mapping belongs to this build: pg_map_id is reported, not compared, and a limitation says so.
Stack-trace retracing.

No speculative race or security hardening was added. The fail-closed rules come from the format itself (record grammar, prototype and type verification) and from refusing to guess between candidates.

Contribution scope: static name annotation from a caller-supplied local file. There's no APK modification, no fetching, no execution and no new provider.

Contract and boundary impact

Semantic owner and earliest changed stage:
- src/domain/android/proguardMapping.ts owns record interpretation and resolution;
- the provider owns file admission.
Contribution scope fit and linked maintainer decision: this follows the plan in my #6329 comment. The first PR is narrower than that plan: class and method inspection only.
CLI and MCP/tool-catalog contract:
- new optional input mapping_path and optional output mapping on two tools;
- two description sentences added, so tools/list grows slightly;
- no new tools.
Provider, bridge, target-format, or platform compatibility:
- The bridge is now version 8. The fields it adds are additive, and REA requires them only when a mapping is selected.
- Open PRs #5248 and #3585 also touch the bridge, so whichever lands second needs a version rebase. I'll handle that on this side.
Evidence, artifact, provenance, or reconstruction contract:
- Evidence keeps mapping_path in its parameters and the file's SHA-256 in the result.
- The subject stays the APK.
- A limitation states that the mapping is not verified against the build.
Target selection, authority, upstream behavior, and cleanup details:
- Mapping errors are input errors returned inside the queue turn, before any session work.
- A relative path is refused by the advertised schema.
- The read uses the provider's existing prerequisite resource scope.
Generated metadata, package, or installation impact: no generated files committed. docs:generate and docs:check pass.

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:

src/domain/android/proguardMapping.test.ts, 25 tests covering:
- header facts, counts and malformed samples (every reason, including members after a bad class line);
- a class mapped only through exactly one record;
- field type verification and type mismatch;
- overloads collapsed to one obfuscated name;
- a lone name-only method candidate that is never mapped;
- members of an ambiguous class;
- the candidate cap;
- original-to-residual type translation;
- residual-signature metadata and an invalid payload;
- inline-frame grouping, and same-range overloads that are not an inline stack;
- CRLF and tab input;
- fail-closed inputs.
tests/boundary/android/JadxAnalysis.test.ts:
- mapping projection for class and method inspection;
- raw-name lookups past JADX aliases;
- the inner-class alignment failure.
tests/boundary/process/androidMappingMcp.test.ts: stdio MCP against the fake JADX server.
- The output validates against the advertised schema.
- Evidence parameters and the APK digest are present.
- Two different mappings run on one engine launch.
- Missing, relative, not-UTF-8, no-class-record and over-budget mappings are each refused with zero launches.
tests/boundary/process/jadxIntegration.test.ts: after a refused mapping, a loaded engine still retires when idle.
tests/acceptance/tools/localToolContracts.test.ts: the contract examples.
tests/conformance/android/ReaJadxMetadataRegression.java (verifyRawMemberNames) plus the RenamedMembers*.smali fixtures. These check that the real bridge reports raw method and field names, dex_type and inner-class raw names for members JADX renames. scripts/verify/android/metadata.mjs asserts RAW_MEMBER_NAME_REGRESSION_PASS.

Base reproduction: I temporarily broke three pieces of logic and confirmed the matching tests fail:

accepting a name-only method match;
choosing a frame other than the outermost inline frame;
looking up display names instead of raw names.

Representative output (fake JADX, inspect_android_class a.b):

"mapping": {
  "file": { "path": "/…/mapping.txt", "sha256": "…" },
  "reported": { "compiler": "R8", "pg_map_id": "7f00" },
  "coverage": { "symbols": 4, "mapped": 4, "ambiguous": 0, "unmapped": 0 },
  "symbols": [
    { "resolution": { "status": "mapped", "mapped": { "name": "com.example.Original" }, "verified_by": "class" } },
    …
    { "resolution": { "status": "mapped", "mapped": { "name": "pick", "parameter_types": ["int"] }, "verified_by": "descriptor" } }
  ]
}

Remaining proof gaps:

The Java bridge wasn't compiled locally (no JDK or JADX jar on this machine). It was compiled and run on the fork by the Real Android metadata bridge workflow (Ubuntu 24.04, JDK 21, checksum-pinned JADX): run 40197903690. That run passed every regression marker, including the new RAW_MEMBER_NAME_REGRESSION_PASS. Later commits don't touch the bridge or its fixtures.
Only synthetic mapping fixtures were used. Real R8 output, such as a large app's mapping.txt, wasn't tested.
Token, CPU and memory costs weren't measured.

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

macOS arm64, pinned Node 24.22.1 / npm 11.19.1, npm ci, branch merged with origin/main at d41c1c6ff:

npm run test:local -- src/domain/android/proguardMapping.test.ts: 25 passed.
npm run test:focused -- tests/boundary/android/JadxAnalysis.test.ts tests/boundary/process/androidAnalysisMcp.test.ts tests/boundary/process/jadxIntegration.test.ts tests/boundary/process/androidMappingMcp.test.ts tests/acceptance/tools/localToolContracts.test.ts: 5 files, 151 passed.
npm run verify:test-discovery: all 2,487 test files discovered once.
npm run check:fast: passed.
node scripts/verify-module-boundaries.mjs: clean.
knip: clean.
npx oxfmt --check on all changed files: clean.
npm run docs:generate && npm run docs:check: passed.
npm run test:fast (after merging main): 18,918 passed, 27 skipped, 0 failed.
The first CI run on this PR failed toolInputReferences, absoluteLocalPathSchema and three other MCP tests. main was failing the same tests at the time (for example on f69c52a1c). After merging the now-green main, they pass locally.

Compatibility, safety, and release

Breaking changes or migration steps:
- None for callers: the input and output fields are optional and additive.
- The packaged bridge source moves to version 8. JadxSession already refuses a bridge that reports a different identity.
Real Hopper/Ghidra, browser, or OS coverage: real bridge run against the pinned engine (JADX_RELEASE 0.7.1) on Linux x64 / JDK 21 through the fork workflow above; macOS and Windows not run.
Package or release metadata impact: none.
Security, privacy, process, or containment review:
- The mapping is a local, caller-selected regular file.
- The path must be absolute, and the size is bounded before reading.
- Malformed samples carry line numbers and reasons but no raw line text.
- Nothing is fetched or written.

Open questions for review

Should selectors also accept mapped names (class_name: "com.example.Original")? I kept v1 to observed names only.
Should REA compare pg_map_id against anything in the APK? Today it only reports the value, with a limitation.
When a class has several records (ambiguous-class), each member of it that has no candidates is reported as unmapped, not ambiguous. Is that the reading you'd expect?

Author readiness

Human owner: @555aaditya

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/7137 **Author:** [@555aaditya](https://github.com/555aaditya) **Created:** 10/25/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/proguard-mapping` --- ### 📝 Commits (4) - [`00ea4aa`](https://github.com/morluto/rea/commit/00ea4aa76e08aedcae57ce2717ebca8f42c2aab8) feat(android): annotate class and method inspection with caller-selected R8/ProGuard mappings - [`9ccccac`](https://github.com/morluto/rea/commit/9ccccacd88620f3528d6a21e194417b98a8b877f) fix(android): keep same-range overloads, serialize mapping reads and index method records - [`d41c1c6`](https://github.com/morluto/rea/commit/d41c1c6ffb201aec8ecebe903995b21f771f346d) Merge remote-tracking branch 'origin/main' into tmp/ci-repro - [`505b95e`](https://github.com/morluto/rea/commit/505b95eb6097e0d1fd8a12710e0f020936e166d1) fix(android): read mappings under the operation deadline and keep idle retirement ### 📊 Changes **26 files changed** (+2228 additions, -88 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/android-applications.md` (+6 -0) 📝 `bridge/android/ReaJadxBridge.java` (+9 -4) 📝 `docs/android-analysis.md` (+53 -0) 📝 `docs/testing.md` (+3 -3) 📝 `scripts/verify/android/metadata.mjs` (+4 -0) ➕ `src/android/AndroidMappingFile.ts` (+181 -0) 📝 `src/android/JadxAnalysis.ts` (+75 -5) 📝 `src/android/JadxProtocol.ts` (+8 -2) 📝 `src/android/JadxProvider.ts` (+48 -4) 📝 `src/android/JadxRelease.ts` (+1 -1) 📝 `src/android/JadxSession.ts` (+17 -3) 📝 `src/cli/androidCommands.ts` (+13 -1) 📝 `src/contracts/android/androidToolContracts.ts` (+10 -2) 📝 `src/domain/android/androidAnalysis.ts` (+17 -8) ➕ `src/domain/android/androidMapping.ts` (+243 -0) ➕ `src/domain/android/dexTypes.ts` (+13 -0) ➕ `src/domain/android/proguardMapping.test.ts` (+353 -0) ➕ `src/domain/android/proguardMapping.ts` (+549 -0) 📝 `tests/acceptance/tools/localToolContracts.test.ts` (+13 -0) 📝 `tests/boundary/android/JadxAnalysis.test.ts` (+322 -54) _...and 6 more files_ </details> ### 📄 Description ## Summary Refs #6329. This is the first of two PRs: it covers class and method inspection. Search and trace come in the follow-up, so the issue stays open. `inspect_android_class` and `inspect_android_method` (and `rea inspect-android-class` / `inspect-android-method --mapping-path`) accept an optional absolute `mapping_path` to an R8/ProGuard `mapping.txt`. The result gains one additive `mapping` block: - the file's path, SHA-256 and size; - header facts the file reports: `compiler`, `compiler_version`, `min_api`, `map_version`, `pg_map_id`, `pg_map_hash`; - valid record counts and up to 16 malformed-line samples; - a resolution for each observed class, inner class, method and field; - coverage counts by status. Observed rows, selectors and Evidence for calls without a mapping are unchanged. Mapped names are reported as claims from the file, never as observations of the APK. ## Problem and expected behavior R8/ProGuard release APKs show names like `a.b.c()`. An analyst who has the build's `mapping.txt` currently has to translate every class and member by hand. Expected behavior: look names up by **raw DEX identity**, not JADX display aliases, and never guess. Each symbol resolves to one of three statuses: | Status | When | |---|---| | `mapped` | Exactly one record matches. Classes verify by raw name (`verified_by: "class"`), methods by DEX prototype (`"descriptor"`), fields by DEX type (`"type"`). R8 `residualsignature` metadata is used when present; otherwise original types are translated through the file's class records. | | `ambiguous` | The reason is `multiple-records`, `descriptor-mismatch`, `type-mismatch` or `ambiguous-class`, with `candidate_count` and up to 8 candidates. A name-only match whose prototype or type doesn't verify is never reported as mapped. | | `unmapped` | No valid record matches the raw identity. | Further behaviour: - **Inline frames:** a line continues a stack when it repeats the previous line's minified range and obfuscated name and gives a single call-site line (`:7`), as R8 writes caller frames. Only the outermost original becomes a candidate. Original line numbers and source files aren't projected. - **Malformed records** are counted and skipped, and parsing continues. - **Refused with an input error, before JADX is touched:** - a file that is missing; - one that is not a regular file; - one that is not UTF-8; - one larger than 64 MiB (`resource_constraint`); - one with no class records at all, such as `usage.txt` or `seeds.txt` passed by mistake. So a bad mapping never launches or retires the JADX session, and switching to a different mapping reuses the loaded APK. ## Change and scope - **Domain (pure):** - `src/domain/android/proguardMapping.ts`: line grammar, inline-frame grouping, residual-signature metadata, malformed samples. - `src/domain/android/androidMapping.ts`: limits, the result schema and `projectAndroidMapping`. - `src/domain/android/dexTypes.ts`: holds `dexDescriptorSchema` and the new `dexTypeSchema`, so the mapping schema can share them without a circular import. - **Provider:** - `src/android/AndroidMappingFile.ts` reads the file through the provider's `#prerequisites` resource scope. - `JadxProvider` reads the mapping inside the request's queue turn and under the operation deadline, before any session work. Only one parsed mapping is held at a time. A refused mapping keeps the loaded session, and its idle timer is rescheduled. - `JadxAnalysis` resolves against the bridge's raw identities. It checks that the display and raw inner-class lists line up, and fails with `AnalysisOutputError` otherwise. - The JADX session cache key is unchanged. - **Bridge (additive, version 7 → 8):** `bridge/android/ReaJadxBridge.java` adds: - `raw_name` on methods; - `raw_name` and `dex_type` on fields (`TypeGen.signature` of the raw field type); - `inner_class_raw_names` on the class summary. `JadxProtocol`, the Java metadata regression and `scripts/verify/android/metadata.mjs` are updated to match, following the shape of #6981. - **Contracts and CLI:** - optional `mapping_path` on the two tools, with an example; - one added sentence in each of the two tool descriptions; - the CLI `--mapping-path` option. - **Docs:** - `docs/android-analysis.md`: a new "Apply an R8/ProGuard mapping" section, the interpretation note and the memory bound; - `docs/testing.md`; - the reverse-engineering skill's Android reference. **Limits** are fixed, with no runtime override (see #6176): - 64 MiB per mapping file; - 16 malformed samples; - 8 candidates per ambiguous symbol. The file is read once per call and parsed in memory, with no caching. **Not included:** - `search_android_classes` and `trace_android_references` (PR 2). - Selecting classes or methods by mapped name. - Checking that a mapping belongs to this build: `pg_map_id` is reported, not compared, and a limitation says so. - Stack-trace retracing. No speculative race or security hardening was added. The fail-closed rules come from the format itself (record grammar, prototype and type verification) and from refusing to guess between candidates. Contribution scope: static name annotation from a caller-supplied local file. There's no APK modification, no fetching, no execution and no new provider. ## Contract and boundary impact - **Semantic owner and earliest changed stage:** - `src/domain/android/proguardMapping.ts` owns record interpretation and resolution; - the provider owns file admission. - **Contribution scope fit and linked maintainer decision:** this follows the plan in my #6329 comment. The first PR is narrower than that plan: class and method inspection only. - **CLI and MCP/tool-catalog contract:** - new optional input `mapping_path` and optional output `mapping` on two tools; - two description sentences added, so `tools/list` grows slightly; - no new tools. - **Provider, bridge, target-format, or platform compatibility:** - The bridge is now **version 8**. The fields it adds are additive, and REA requires them only when a mapping is selected. - Open PRs **#5248** and **#3585** also touch the bridge, so whichever lands second needs a version rebase. I'll handle that on this side. - **Evidence, artifact, provenance, or reconstruction contract:** - Evidence keeps `mapping_path` in its parameters and the file's SHA-256 in the result. - The subject stays the APK. - A limitation states that the mapping is not verified against the build. - **Target selection, authority, upstream behavior, and cleanup details:** - Mapping errors are input errors returned inside the queue turn, before any session work. - A relative path is refused by the advertised schema. - The read uses the provider's existing prerequisite resource scope. - **Generated metadata, package, or installation impact:** no generated files committed. `docs:generate` and `docs:check` pass. 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:** - `src/domain/android/proguardMapping.test.ts`, 25 tests covering: - header facts, counts and malformed samples (every reason, including members after a bad class line); - a class mapped only through exactly one record; - field type verification and type mismatch; - overloads collapsed to one obfuscated name; - a lone name-only method candidate that is never mapped; - members of an ambiguous class; - the candidate cap; - original-to-residual type translation; - residual-signature metadata and an invalid payload; - inline-frame grouping, and same-range overloads that are not an inline stack; - CRLF and tab input; - fail-closed inputs. - `tests/boundary/android/JadxAnalysis.test.ts`: - mapping projection for class and method inspection; - raw-name lookups past JADX aliases; - the inner-class alignment failure. - `tests/boundary/process/androidMappingMcp.test.ts`: stdio MCP against the fake JADX server. - The output validates against the advertised schema. - Evidence parameters and the APK digest are present. - Two different mappings run on **one** engine launch. - Missing, relative, not-UTF-8, no-class-record and over-budget mappings are each refused **with zero launches**. - `tests/boundary/process/jadxIntegration.test.ts`: after a refused mapping, a loaded engine still retires when idle. - `tests/acceptance/tools/localToolContracts.test.ts`: the contract examples. - `tests/conformance/android/ReaJadxMetadataRegression.java` (`verifyRawMemberNames`) plus the `RenamedMembers*.smali` fixtures. These check that the real bridge reports raw method and field names, `dex_type` and inner-class raw names for members JADX renames. `scripts/verify/android/metadata.mjs` asserts `RAW_MEMBER_NAME_REGRESSION_PASS`. **Base reproduction:** I temporarily broke three pieces of logic and confirmed the matching tests fail: - accepting a name-only method match; - choosing a frame other than the outermost inline frame; - looking up display names instead of raw names. **Representative output** (fake JADX, `inspect_android_class a.b`): ```json "mapping": { "file": { "path": "/…/mapping.txt", "sha256": "…" }, "reported": { "compiler": "R8", "pg_map_id": "7f00" }, "coverage": { "symbols": 4, "mapped": 4, "ambiguous": 0, "unmapped": 0 }, "symbols": [ { "resolution": { "status": "mapped", "mapped": { "name": "com.example.Original" }, "verified_by": "class" } }, … { "resolution": { "status": "mapped", "mapped": { "name": "pick", "parameter_types": ["int"] }, "verified_by": "descriptor" } } ] } ``` **Remaining proof gaps:** - The Java bridge wasn't compiled locally (no JDK or JADX jar on this machine). It was compiled and run on the fork by the `Real Android metadata bridge` workflow (Ubuntu 24.04, JDK 21, checksum-pinned JADX): [run 40197903690](https://github.com/555aaditya/rea/actions/runs/40197903690). That run passed every regression marker, including the new `RAW_MEMBER_NAME_REGRESSION_PASS`. Later commits don't touch the bridge or its fixtures. - Only synthetic mapping fixtures were used. Real R8 output, such as a large app's `mapping.txt`, wasn't tested. - Token, CPU and memory costs weren't measured. 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 macOS arm64, pinned Node 24.22.1 / npm 11.19.1, `npm ci`, branch merged with `origin/main` at `d41c1c6ff`: - `npm run test:local -- src/domain/android/proguardMapping.test.ts`: 25 passed. - `npm run test:focused -- tests/boundary/android/JadxAnalysis.test.ts tests/boundary/process/androidAnalysisMcp.test.ts tests/boundary/process/jadxIntegration.test.ts tests/boundary/process/androidMappingMcp.test.ts tests/acceptance/tools/localToolContracts.test.ts`: 5 files, 151 passed. - `npm run verify:test-discovery`: all 2,487 test files discovered once. - `npm run check:fast`: passed. - `node scripts/verify-module-boundaries.mjs`: clean. - knip: clean. - `npx oxfmt --check` on all changed files: clean. - `npm run docs:generate && npm run docs:check`: passed. - `npm run test:fast` (after merging main): 18,918 passed, 27 skipped, 0 failed. - The first CI run on this PR failed `toolInputReferences`, `absoluteLocalPathSchema` and three other MCP tests. `main` was failing the same tests at the time (for example on `f69c52a1c`). After merging the now-green `main`, they pass locally. ## Compatibility, safety, and release - **Breaking changes or migration steps:** - None for callers: the input and output fields are optional and additive. - The packaged bridge source moves to version 8. `JadxSession` already refuses a bridge that reports a different identity. - **Real Hopper/Ghidra, browser, or OS coverage:** real bridge run against the pinned engine (`JADX_RELEASE` 0.7.1) on Linux x64 / JDK 21 through the fork workflow above; macOS and Windows not run. - **Package or release metadata impact:** none. - **Security, privacy, process, or containment review:** - The mapping is a local, caller-selected regular file. - The path must be absolute, and the size is bounded before reading. - Malformed samples carry line numbers and reasons but no raw line text. - Nothing is fetched or written. ### Open questions for review 1. Should selectors also accept mapped names (`class_name: "com.example.Original"`)? I kept v1 to observed names only. 2. Should REA compare `pg_map_id` against anything in the APK? Today it only reports the value, with a limitation. 3. When a class has several records (`ambiguous-class`), each member of it that has no candidates is reported as `unmapped`, not `ambiguous`. Is that the reading you'd expect? ## Author readiness  Human owner: @555aaditya - [x] 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. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] 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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:39:29 +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#7667

No description provided.

Rows
Columns