morluto/rea

Fork 0

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

Hooks graph, RSC flight decoding, and Hermes unbundling #1340

New issue

Open

opened 2026-10-16 21:04:28 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:04:28 +00:00

Owner

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

Summary

React is the dominant UI library across Web applications (SPAs, Next.js, Remix), Desktop applications (Electron ASAR bundles), and Mobile applications (React Native via Hermes bytecode). However, in production builds, React source code undergoes aggressive compilation and minification that completely obscure its component hierarchy, state flow, and routing topology.

This RFC proposes the design and architecture of a dedicated React Semantic Reconstruction & Decompiler Engine for REA, providing deep, inert de-sugaring of JSX, recovery of component trees and custom hooks, decoding of React Server Components (RSC) and Server Actions, and decompilation/unbundling of React Native Hermes bytecode.

Current State and Limitations in REA

Currently, REA's JavaScript and mobile analysis provides only shallow, surface-level handling for React targets:

Vendor Detection Only: React is detected solely as a vendor signature via static strings (["React.createElement", "react/jsx-runtime"] in src/domain/javascript/javascriptStaticAnalysisHelpers.ts and __REACT_DEVTOOLS_GLOBAL_HOOK__ in webBundleAnalyzerInspection.ts).
False Positive Guard Only: In javascriptStaticAnalysisCalls.ts, element factories like jsx("audio", props) are checked only to prevent misinterpreting <audio preload="metadata"> or <video> as Electron preload scripts.
Generic Module Unbundling Without Component Semantics: WakaruProvider (src/javascript/recovery/WakaruProvider.ts) invokes @wakaru/unpacker to split Webpack/Vite chunks into separate files, but leaves minified element factories (_jsx, _jsxs, React.createElement), hook invocations, and mangled component closures untouched.
Unanalyzed Mobile Bytecode: In Android APKs and iOS apps, Hermes bytecode (libhermes.so, index.android.bundle in .hbc format) is only noted by filename convention in docs/android-analysis.md and docs/apple-application-analysis.md, with no Hermes bytecode disassembler or Metro unbundler available.

Proposed Architecture: React Semantic Reconstruction Engine

                                    +-----------------------------------------+
                                    | Input: Web Bundle / ASAR / Hermes .hbc  |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           |  Web / Electron Bundles   |                                   |  React Native Hermes HBC  |
           |   (Webpack, Vite, esbuild)|                                   |  (.hbc bytecode, Metro)   |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         |                                                 +-------------v-------------+
                         |                                                 | Hermes Bytecode Parser    |
                         |                                                 | & Metro Module Unbundler  |
                         |                                                 +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Layer 1: JSX De-sugaring & AST        |
                                     | Inversion (_jsx, _jsxs, createElement)|
                                     +-------------------+-------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | Layer 2: Component Tree & Virtual DOM |
                                     | Recovery (displayName, memo, HOCs)    |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                               |                               |
                         v                               v                               v
           +---------------------------+   +---------------------------+   +---------------------------+
           | Layer 3: Hooks & State    |   | Layer 4: Router Topology  |   | Layer 5: RSC Flight &     |
           | Graph (Redux, Zustand,    |   | (React Router, Next.js,   |   | Server Actions            |
           | TanStack Query, effects)  |   | route guards, API links)  |   | ("use server", $ACTION_ID)|
           +---------------------------+   +---------------------------+   +---------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence / JavaScript Graph Nodes |
                                     | (inspect_analysis_view, CLI, MCP)     |
                                     +---------------------------------------+

1. JSX De-sugaring & AST Inversion (Element Factory Decompilation)

Runtime Inversion: Transform minified call expressions into native JSX AST nodes (JSXElement, JSXFragment, JSXOpeningElement, JSXAttribute):
- Classic Runtime: React.createElement(Component, props, ...children)
- Automatic Runtime (React 17+): (0, _jsxRuntime.jsx)(Component, { foo: 'bar', children: ... }) and jsxs
- Factory Aliases: Bounded lexical resolution of bundler wrapper identifiers (e.g. (0, a.jsx)(b.Card, { ... }) -> <b.Card ...>).
Fragments & Special Props: Normalize _Fragment / React.Fragment to <>...</>, restore key and ref attributes from factory argument positions, and expand prop spreads ({...props}).
React 19 / React Compiler (Forget) Handling: Recognize and de-sugar memo cache slots (useMemoCache, _c(...)), extracting the underlying un-memoized component logic.

2. Component Hierarchy & Virtual DOM Recovery

Component Identification: Heuristically identify React components by detecting functions that:
- Return JSX element nodes / element factory calls.
- Call React hooks (useState, useEffect, etc.).
- Are wrapped in standard HOCs (memo(), forwardRef(), withRouter()).
Component Name Reconstruction:
- Recover explicit displayName assignments (Component.displayName = 'UserCard').
- Reconcile export names and variable declarators (export default function Header(), const Sidebar = memo(...)).
- Leverage source map identifier names (names array in decoded source maps).
- Inspect residual React DevTools markers (__REACT_DEVTOOLS_GLOBAL_HOOK__ and Fiber tags).
Visual Hierarchy Graph: Build parent-child relationships (App -> RootLayout -> Header + MainContent -> UserProfileCard), annotating props passed to child components.

3. Hooks, State Graph & Dataflow Analysis

Core Hook Extraction:
- State: useState (infer descriptive names from destructuring patterns const [user, setUser] = ...), useReducer.
- Lifecycle & Side Effects: useEffect, useLayoutEffect, useInsertionEffect (recording dependency arrays and identifying data fetch triggers).
- Context: trace createContext instances and consumers via useContext.
- React 19 Hooks: use(), useActionState(), useOptimistic(), useFormStatus().
Custom Hooks: Map functions matching /^use[A-Z]\w*/ that encapsulate business logic.
Global Store & Data-Fetching Discovery:
- Zustand: Parse create((set) => ({ ... })) calls to extract state stores and action dispatches.
- Redux / Redux Toolkit: Recover createSlice, action creators, and useSelector / useDispatch usages.
- TanStack Query / SWR: Extract queryKey tuples and mutation endpoints, linking UI buttons/forms directly to external API requests.

4. Routing Topology & API Surface Mapping

Router Discovery: Extract route definitions from:
- React Router (createBrowserRouter, createHashRouter, <Route path="..." element={<Page />} />, useRoutes).
- Next.js (Pages Router pages/**/*.js and App Router app/**/{page,layout,loading,error}.js).
- TanStack Router and Remix route configurations.
Route Protection & Guards: Identify authentication middleware and wrapper components (<ProtectedRoute>, <RequireAuth>).
Component-to-Endpoint Binding: Correlate user interactions (e.g. form submit, button click) with HTTP/RPC calls (fetch, axios, tRPC procedures, GraphQL operations).

5. React Server Components (RSC) & Server Actions (Next.js / React 19)

RSC Flight Stream Parser: Implement an offline decoder for the React Flight streaming wire format (e.g. 0:["$","div",null,{"children":"..."}] or chunks with client references 1:I("chunk.js", ["ClientComponent"], "")), reconstructing the server-rendered component tree.
Server Actions Extraction: Identify "use server" directive boundaries and $ACTION_ID_... closures, mapping exposed server endpoints accessible from client bundles.
Client Reference Manifest: Parse client-reference-manifest.json to link server layouts with client component chunks.

6. React Native & Hermes Bytecode (HBC) Decompilation

Hermes Bytecode Decompiler / Disassembler: Provide an inert, headless parser for .hbc bytecode files across major format versions (HBC 76 through 96+), recovering function tables, string pools, and instruction streams.
Metro Bundle Unbundler: Parse the Metro runtime envelope __d(function(global, require, importDefault, ...) { ... }, moduleId, [dependencies]), reconstructing individual JavaScript module files.
JSI & TurboModule Bindings: Trace invocations of native bridge interfaces (NativeModules.*, TurboModuleRegistry.getEnforcing(...)), linking React Native components to underlying Android Java/Kotlin and iOS Objective-C/Swift native methods.

Integration into REA Contracts

Existing Tools: Integrate directly into analyze_javascript_application, analyze_web_bundle, and mobile inspection workflows.
Structured Evidence: Add React-specific node types (react-component, react-hook, react-route, react-store, rsc-action) to the JavaScript Application Graph (docs/javascript-application-graph.md).
Safety & Resource Budgets: Adhere to REA's strict non-executing design (no DOM execution, no eval, bounded traversal depth of 256 levels, and explicit limits on memory expansion).

Acceptance Criteria

Invert minified _jsx, _jsxs, and React.createElement calls into clean JSX ASTs with accurate children and prop representations across synthetic test bundles.
Reconstruct component trees and infer component names using displayName, export bindings, and source map hints.
Extract native and custom hook usages, pairing useState getters with setters and recording useEffect dependencies.
Decode static RSC Flight payloads into structured component trees and identify Server Action identifiers.
Disassemble and unbundle Hermes .hbc / Metro bundles into modular JavaScript files with verified digests.
Return typed, actionable diagnostic errors when bundles are corrupted, obfuscated with unsupported packers, or exceed resource limits.

#861 analyze-javascript-application: unreadable_output '/label (too_small)' on a Vite bundle
#1670 feat(javascript): recognize tRPC procedures and GraphQL operations
#3607 [Feature] Comprehensive Unity extraction and reverse engineering
docs/javascript-artifact-reconstruction.md

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3608 [![Type: Architecture / RFC](https://img.shields.io/badge/type-architecture_%2F_RFC-darkred.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) ## Summary React is the dominant UI library across Web applications (SPAs, Next.js, Remix), Desktop applications (Electron ASAR bundles), and Mobile applications (React Native via Hermes bytecode). However, in production builds, React source code undergoes aggressive compilation and minification that completely obscure its component hierarchy, state flow, and routing topology. This RFC proposes the design and architecture of a dedicated **React Semantic Reconstruction & Decompiler Engine** for REA, providing deep, inert de-sugaring of JSX, recovery of component trees and custom hooks, decoding of React Server Components (RSC) and Server Actions, and decompilation/unbundling of React Native Hermes bytecode. --- ## Current State and Limitations in REA Currently, REA's JavaScript and mobile analysis provides only shallow, surface-level handling for React targets: 1. **Vendor Detection Only:** React is detected solely as a vendor signature via static strings (`["React.createElement", "react/jsx-runtime"]` in `src/domain/javascript/javascriptStaticAnalysisHelpers.ts` and `__REACT_DEVTOOLS_GLOBAL_HOOK__` in `webBundleAnalyzerInspection.ts`). 2. **False Positive Guard Only:** In `javascriptStaticAnalysisCalls.ts`, element factories like `jsx("audio", props)` are checked only to prevent misinterpreting `<audio preload="metadata">` or `<video>` as Electron preload scripts. 3. **Generic Module Unbundling Without Component Semantics:** `WakaruProvider` (`src/javascript/recovery/WakaruProvider.ts`) invokes `@wakaru/unpacker` to split Webpack/Vite chunks into separate files, but leaves minified element factories (`_jsx`, `_jsxs`, `React.createElement`), hook invocations, and mangled component closures untouched. 4. **Unanalyzed Mobile Bytecode:** In Android APKs and iOS apps, Hermes bytecode (`libhermes.so`, `index.android.bundle` in `.hbc` format) is only noted by filename convention in `docs/android-analysis.md` and `docs/apple-application-analysis.md`, with no Hermes bytecode disassembler or Metro unbundler available. --- ## Proposed Architecture: React Semantic Reconstruction Engine ``` +-----------------------------------------+ | Input: Web Bundle / ASAR / Hermes .hbc | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | Web / Electron Bundles | | React Native Hermes HBC | | (Webpack, Vite, esbuild)| | (.hbc bytecode, Metro) | +-------------+-------------+ +-------------+-------------+ | | | +-------------v-------------+ | | Hermes Bytecode Parser | | | & Metro Module Unbundler | | +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | Layer 1: JSX De-sugaring & AST | | Inversion (_jsx, _jsxs, createElement)| +-------------------+-------------------+ | v +---------------------------------------+ | Layer 2: Component Tree & Virtual DOM | | Recovery (displayName, memo, HOCs) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | | v v v +---------------------------+ +---------------------------+ +---------------------------+ | Layer 3: Hooks & State | | Layer 4: Router Topology | | Layer 5: RSC Flight & | | Graph (Redux, Zustand, | | (React Router, Next.js, | | Server Actions | | TanStack Query, effects) | | route guards, API links) | | ("use server", $ACTION_ID)| +---------------------------+ +---------------------------+ +---------------------------+ | v +---------------------------------------+ | REA Evidence / JavaScript Graph Nodes | | (inspect_analysis_view, CLI, MCP) | +---------------------------------------+ ``` ### 1. JSX De-sugaring & AST Inversion (Element Factory Decompilation) - **Runtime Inversion:** Transform minified call expressions into native JSX AST nodes (`JSXElement`, `JSXFragment`, `JSXOpeningElement`, `JSXAttribute`): - Classic Runtime: `React.createElement(Component, props, ...children)` - Automatic Runtime (React 17+): `(0, _jsxRuntime.jsx)(Component, { foo: 'bar', children: ... })` and `jsxs` - Factory Aliases: Bounded lexical resolution of bundler wrapper identifiers (e.g. `(0, a.jsx)(b.Card, { ... })` -> `<b.Card ...>`). - **Fragments & Special Props:** Normalize `_Fragment` / `React.Fragment` to `<>...</>`, restore `key` and `ref` attributes from factory argument positions, and expand prop spreads (`{...props}`). - **React 19 / React Compiler (Forget) Handling:** Recognize and de-sugar memo cache slots (`useMemoCache`, `_c(...)`), extracting the underlying un-memoized component logic. ### 2. Component Hierarchy & Virtual DOM Recovery - **Component Identification:** Heuristically identify React components by detecting functions that: - Return JSX element nodes / element factory calls. - Call React hooks (`useState`, `useEffect`, etc.). - Are wrapped in standard HOCs (`memo()`, `forwardRef()`, `withRouter()`). - **Component Name Reconstruction:** - Recover explicit `displayName` assignments (`Component.displayName = 'UserCard'`). - Reconcile export names and variable declarators (`export default function Header()`, `const Sidebar = memo(...)`). - Leverage source map identifier names (`names` array in decoded source maps). - Inspect residual React DevTools markers (`__REACT_DEVTOOLS_GLOBAL_HOOK__` and Fiber tags). - **Visual Hierarchy Graph:** Build parent-child relationships (`App -> RootLayout -> Header + MainContent -> UserProfileCard`), annotating props passed to child components. ### 3. Hooks, State Graph & Dataflow Analysis - **Core Hook Extraction:** - State: `useState` (infer descriptive names from destructuring patterns `const [user, setUser] = ...`), `useReducer`. - Lifecycle & Side Effects: `useEffect`, `useLayoutEffect`, `useInsertionEffect` (recording dependency arrays and identifying data fetch triggers). - Context: trace `createContext` instances and consumers via `useContext`. - React 19 Hooks: `use()`, `useActionState()`, `useOptimistic()`, `useFormStatus()`. - **Custom Hooks:** Map functions matching `/^use[A-Z]\w*/` that encapsulate business logic. - **Global Store & Data-Fetching Discovery:** - **Zustand:** Parse `create((set) => ({ ... }))` calls to extract state stores and action dispatches. - **Redux / Redux Toolkit:** Recover `createSlice`, action creators, and `useSelector` / `useDispatch` usages. - **TanStack Query / SWR:** Extract `queryKey` tuples and mutation endpoints, linking UI buttons/forms directly to external API requests. ### 4. Routing Topology & API Surface Mapping - **Router Discovery:** Extract route definitions from: - React Router (`createBrowserRouter`, `createHashRouter`, `<Route path="..." element={<Page />} />`, `useRoutes`). - Next.js (Pages Router `pages/**/*.js` and App Router `app/**/{page,layout,loading,error}.js`). - TanStack Router and Remix route configurations. - **Route Protection & Guards:** Identify authentication middleware and wrapper components (`<ProtectedRoute>`, `<RequireAuth>`). - **Component-to-Endpoint Binding:** Correlate user interactions (e.g. form submit, button click) with HTTP/RPC calls (fetch, axios, tRPC procedures, GraphQL operations). ### 5. React Server Components (RSC) & Server Actions (Next.js / React 19) - **RSC Flight Stream Parser:** Implement an offline decoder for the React Flight streaming wire format (e.g. `0:["$","div",null,{"children":"..."}]` or chunks with client references `1:I("chunk.js", ["ClientComponent"], "")`), reconstructing the server-rendered component tree. - **Server Actions Extraction:** Identify `"use server"` directive boundaries and `$ACTION_ID_...` closures, mapping exposed server endpoints accessible from client bundles. - **Client Reference Manifest:** Parse `client-reference-manifest.json` to link server layouts with client component chunks. ### 6. React Native & Hermes Bytecode (HBC) Decompilation - **Hermes Bytecode Decompiler / Disassembler:** Provide an inert, headless parser for `.hbc` bytecode files across major format versions (HBC 76 through 96+), recovering function tables, string pools, and instruction streams. - **Metro Bundle Unbundler:** Parse the Metro runtime envelope `__d(function(global, require, importDefault, ...) { ... }, moduleId, [dependencies])`, reconstructing individual JavaScript module files. - **JSI & TurboModule Bindings:** Trace invocations of native bridge interfaces (`NativeModules.*`, `TurboModuleRegistry.getEnforcing(...)`), linking React Native components to underlying Android Java/Kotlin and iOS Objective-C/Swift native methods. --- ## Integration into REA Contracts - **Existing Tools:** Integrate directly into `analyze_javascript_application`, `analyze_web_bundle`, and mobile inspection workflows. - **Structured Evidence:** Add React-specific node types (`react-component`, `react-hook`, `react-route`, `react-store`, `rsc-action`) to the JavaScript Application Graph (`docs/javascript-application-graph.md`). - **Safety & Resource Budgets:** Adhere to REA's strict non-executing design (no DOM execution, no `eval`, bounded traversal depth of 256 levels, and explicit limits on memory expansion). --- ## Acceptance Criteria 1. Invert minified `_jsx`, `_jsxs`, and `React.createElement` calls into clean JSX ASTs with accurate children and prop representations across synthetic test bundles. 2. Reconstruct component trees and infer component names using `displayName`, export bindings, and source map hints. 3. Extract native and custom hook usages, pairing `useState` getters with setters and recording `useEffect` dependencies. 4. Decode static RSC Flight payloads into structured component trees and identify Server Action identifiers. 5. Disassemble and unbundle Hermes `.hbc` / Metro bundles into modular JavaScript files with verified digests. 6. Return typed, actionable diagnostic errors when bundles are corrupted, obfuscated with unsupported packers, or exceed resource limits. --- ## Related - #861 analyze-javascript-application: unreadable_output '/label (too_small)' on a Vite bundle - #1670 feat(javascript): recognize tRPC procedures and GraphQL operations - #3607 [Feature] Comprehensive Unity extraction and reverse engineering - docs/javascript-artifact-reconstruction.md

bsakaguchi referenced this issue

2026-10-17 21:10:30 +00:00

[PR #1340] [MERGED] chore(release): sync 6.2.0 checkpoint into main #2808

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#1340

No description provided.

Rows
Columns