references/javascript-applications.md
11.7 KB查看排版效果| 1 | # JavaScript and Electron application artifacts |
| 2 | |
| 3 | For captured or bundled JavaScript that needs readable source recovery, use |
| 4 | `recover_javascript_sources` with an absolute `path` and absent |
| 5 | `output_directory`. Supply related runtime/shared/lazy files in |
| 6 | `additional_paths` when advertised, then analyze the returned `analysis_input` |
| 7 | directory together. Each input retains its own snapshot, digest and byte-range |
| 8 | provenance; inputs and recovered code are never executed. Recovery requires a |
| 9 | caller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/javascript-recovery.md). |
| 10 | |
| 11 | Use `analyze_javascript_application` directly on the operator-supplied ASAR or |
| 12 | extracted tree. When the question concerns known source paths and the connected |
| 13 | schema advertises `source_paths`, select exact inventoried paths such as |
| 14 | `["package.json", "main.js", "preload.js"]`. Include supporting manifests or |
| 15 | source maps explicitly; dependencies are not implicitly analyzed. REA retains |
| 16 | the complete artifact inventory and identity but reads source text and analyzes |
| 17 | only selected files. The result and summary record `source_selection`; files |
| 18 | outside scope and their relationships remain unknown, so partial application |
| 19 | coverage does not mean the selected source failed. Use repeated `--source-path` |
| 20 | on either static application CLI route. Omit the selection when the question |
| 21 | requires complete application analysis. `detail: "summary"` reduces delivery |
| 22 | and does not by itself reduce analysis work. |
| 23 | |
| 24 | Exact `#alias` specifiers resolve through the importer's |
| 25 | enclosing package `imports` map to package-local files; nested `node_modules` |
| 26 | packages use their own map. Wildcard, recursive, and external-package import |
| 27 | targets stay unresolved with that limitation. When size is unknown or large and the connected schema advertises |
| 28 | `detail`, request `detail: "summary"`. This returns an `inspect_analysis_view` |
| 29 | Evidence record with a distinct ID and a `normalized_result.parent_evidence_id` |
| 30 | for the complete retained application analysis. Source-map contents are part of |
| 31 | that static analysis. Read findings, coverage, limitations and unknowns, then |
| 32 | follow a specific unanswered question. Older servers without `detail` return |
| 33 | the complete application Evidence inline when it fits. |
| 34 | |
| 35 | When the connected schema advertises `max_heap_mb` and `analysis_timeout_ms`, |
| 36 | these select the isolated source analyzer's old-space heap and per-source |
| 37 | deadline. Defaults are 1024 MiB and 300000 ms. They do not change the MCP |
| 38 | process heap. A Bun-hosted REA does not enforce the heap choice; on Windows it |
| 39 | instead limits the analyzer's committed memory to that choice plus a 512 MiB |
| 40 | runtime reserve. |
| 41 | Resource-limited analyses preserve completed static facts and |
| 42 | report partial semantic coverage with specific unknown scopes; this does not |
| 43 | mean the source is malformed. Inspect those limits before retrying a source. |
| 44 | When expanded relationships exceed the parent's available memory, inspect the |
| 45 | file's modules item view for retained `static_analysis` and |
| 46 | `semantic_module_analysis`. Their facts remain available even when graph links |
| 47 | are unknown. Cumulative result exhaustion can stop analysis before every file |
| 48 | is examined; the inventory and remaining unknown scopes distinguish that case. |
| 49 | Timeout or cancellation after source analysis begins retains partial Evidence |
| 50 | in the same session. A returned `error.details.partial_observation` reference |
| 51 | can be supplied directly to `inspect_analysis_view`. If the SDK cancels locally, retrieve its recorded ID from |
| 52 | the Evidence bundle before inspecting the partial analysis. |
| 53 | |
| 54 | ## Read a module without repeating analysis |
| 55 | |
| 56 | Use the actual returned parent ID, on the same connection, as `source.evidence_id`. |
| 57 | The following IDs are placeholders to replace with returned values. When the |
| 58 | module's node ID is not already known, page identities before selecting an item. |
| 59 | Pages return only node IDs, paths and roles; choose a useful page size and follow |
| 60 | `coverage.next_offset` when another page matters: |
| 61 | |
| 62 | ```json |
| 63 | { |
| 64 | "source": { |
| 65 | "kind": "retained-evidence", |
| 66 | "evidence_id": "ev_ACTUAL_PARENT_ID" |
| 67 | }, |
| 68 | "view": { "kind": "page", "collection": "modules", "offset": 0, "limit": 16 } |
| 69 | } |
| 70 | ``` |
| 71 | |
| 72 | Select the relevant page entry by its exact `node_id` and recorded role: |
| 73 | |
| 74 | ```json |
| 75 | { |
| 76 | "source": { |
| 77 | "kind": "retained-evidence", |
| 78 | "evidence_id": "ev_ACTUAL_PARENT_ID" |
| 79 | }, |
| 80 | "view": { |
| 81 | "kind": "item", |
| 82 | "collection": "modules", |
| 83 | "selector": { "node_id": "jag_node_ACTUAL_NODE_ID" } |
| 84 | } |
| 85 | } |
| 86 | ``` |
| 87 | |
| 88 | Module pages include asset, bundled and source module roles, so one path can |
| 89 | identify several entries. Use `selector.path` only when uniqueness is established; |
| 90 | the returned node ID avoids needing a complete inventory to prove uniqueness. On ambiguity, |
| 91 | select the matching node ID from the page or the error's candidates. Follow |
| 92 | `next_offset` when another page matters. An item exposes that module node's |
| 93 | recorded observations, identity, hashes, exports and source ranges; it does not |
| 94 | include every child syntax observation, related edge or original source file. |
| 95 | An absent item fact is not evidence of absence from the whole application. |
| 96 | |
| 97 | For canonical identities and retained source-range counts, use a typed reference |
| 98 | page instead of reading every full item: |
| 99 | |
| 100 | ```json |
| 101 | { |
| 102 | "source": { |
| 103 | "kind": "retained-evidence", |
| 104 | "evidence_id": "ev_ACTUAL_PARENT_ID" |
| 105 | }, |
| 106 | "view": { |
| 107 | "kind": "javascript", |
| 108 | "collection": "modules", |
| 109 | "projection": "references", |
| 110 | "where": { "path": "main.js", "kind": "javascript-module" }, |
| 111 | "offset": 0, |
| 112 | "limit": 16 |
| 113 | } |
| 114 | } |
| 115 | ``` |
| 116 | |
| 117 | Filters match exact retained strings; omit a filter to include all values, use |
| 118 | `path: null` for unavailable paths, and `path: ""` for a recorded empty path. |
| 119 | Rows preserve canonical `identity` and distinct observation support states in |
| 120 | `basis`. `retained_source_range_count` counts retained source-range observations, |
| 121 | not runtime imports or unique reference sites. Use a row's `node_id` with the item |
| 122 | view above for exact locations and full supporting observations. Follow |
| 123 | `coverage.next_offset`; page exhaustion describes matching retained rows only. |
| 124 | Check `source_coverage` for source selection, partial/unknown graph coverage and |
| 125 | unknown counts before drawing a negative conclusion. |
| 126 | |
| 127 | ## Trace only the remaining question |
| 128 | |
| 129 | Use `trace_application_feature` on the parent application Evidence for one |
| 130 | literal node ID, route, string, API, IPC channel, module, or native export. |
| 131 | Select `incoming` for relationships leading to the seed, `outgoing` for those |
| 132 | leaving it, and `both` when the question needs both. Trace traversal includes |
| 133 | containment relationships, so even a narrow seed can expand many nodes; a |
| 134 | bidirectional trace can reach unrelated sibling modules. A module item or page |
| 135 | is preferable when its observations already answer the question. Do not treat |
| 136 | all reached nodes as participants in the feature. |
| 137 | |
| 138 | Reuse retained parent Evidence when the server advertises it, or supply complete |
| 139 | Evidence inline. Include Hopper or Ghidra Evidence only when its artifact digest |
| 140 | matches exactly. |
| 141 | |
| 142 | ## Recover an oversized display |
| 143 | |
| 144 | An oversized response reports `resource_constraint` and |
| 145 | `details.resource: "transport"`. Reuse |
| 146 | `details.reported_limits.evidence_reference` with `inspect_analysis_view` for a |
| 147 | summary, one module, or a stable page of module identities. |
| 148 | `export_evidence_bundle` writes the complete canonical session to a |
| 149 | caller-selected file. These workflows keep the original Evidence and coverage; |
| 150 | a broad follow-up can also exceed framing. |
| 151 | |
| 152 | A client can truncate a successful result inside its text envelope without a |
| 153 | REA `resource_constraint`. Treat a truncation notice or incomplete JSON as a |
| 154 | display limitation; do not claim the full record was examined. Reuse the known |
| 155 | parent ID for smaller views, or export complete Evidence to a selected file |
| 156 | while the session remains open. If the parent ID was lost from the preview, |
| 157 | use the prior analysis summary or explicit ledger entries to recover it; do |
| 158 | not invent an ID or rerun analysis just to reproduce the same display. |
| 159 | |
| 160 | BrowserWindow preferences, preload and contextBridge surfaces, IPC |
| 161 | registrations, utility processes, and native binding requests are static syntax |
| 162 | observations. Only a unique exact literal IPC channel match supports an inferred |
| 163 | pairing. Dynamic or ambiguous channels remain unresolved. A requested `.node` |
| 164 | member is not a verified native export. Never claim runtime reachability, |
| 165 | registration, defaults, or policy enforcement from static analysis. |
| 166 | |
| 167 | For version comparison, analyze each version once, then call |
| 168 | `compare_application_versions`. Accept only its digest, source-map, structural |
| 169 | fingerprint, or non-module semantic matches. Module ordinals and minified names |
| 170 | are not persistent identity. Report added or removed only with complete |
| 171 | opposite-side coverage; otherwise report unknown. |
| 172 | |
| 173 | When the question asks how one exact exported callable's returned object shape |
| 174 | changed, analyze each version once and then call |
| 175 | `compare_javascript_export_shapes` with explicit module paths and export names. |
| 176 | Use the returned IDs on the same connection, or complete inline Evidence |
| 177 | records, from both analysis calls. Accept variant |
| 178 | pairing only through the tool's unique exact literal discriminant. Read |
| 179 | `property_inventories` and each change's `presence` before treating `unknown` as |
| 180 | "the name was not observed": inventories list observed property names even when |
| 181 | values stay unknown, with a `source_range` for each paired or unpaired variant. |
| 182 | Array holes and mutation-invalidated slots are not observed properties. |
| 183 | Complete parent coverage reports presence-only |
| 184 | `added`/`removed` independently of unresolved values. Cite the |
| 185 | comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous |
| 186 | variants, and incomplete parent-property coverage stay unknown. This is static |
| 187 | inference, not runtime behavior. When runtime semantics are needed, run |
| 188 | behavioral probes against the relevant application versions and capture them |
| 189 | through the available browser, Electron, or process workflows. |
| 190 | |
| 191 | ## Reusing application Evidence |
| 192 | |
| 193 | When advertised by the connected server, application trace and compare tools |
| 194 | accept complete inline Evidence or |
| 195 | `{"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}` |
| 196 | for their application input (`application`, or `left`/`right`). `inspect_analysis_view` |
| 197 | uses the same retained-reference form in `source`, or portable inline Evidence, |
| 198 | to project a summary, module page, or one module with its recorded observations. |
| 199 | This notation is |
| 200 | a template: replace it with the actual returned ID. Versions before 4.1.0 accept only full |
| 201 | inline Evidence. Use the exact ID |
| 202 | returned by the producer on the same MCP connection. Resolution does not run |
| 203 | analysis or select a provider; findings remain inline. Native observation |
| 204 | arrays still take full Evidence. `close_binary` clears retained references; |
| 205 | export a bundle before closing, or supply portable inline Evidence in another |
| 206 | connection. A missing reference includes its ID and recovery guidance. |
| 207 | |
| 208 | For exact file/native metadata or processing gaps, use |
| 209 | `view: {kind: "javascript-facts", where: {paths: ["package.json"]}, property_keys: ["name", "operation", "analysis_status"], limit: 32}`. |
| 210 | Rows retain canonical node/observation identity and original Evidence. Paths |
| 211 | match Evidence artifact-path/source-range locations; missing properties remain |
| 212 | omitted and source coverage stays separate from page exhaustion. Batch paths and |
| 213 | select only needed property keys; complete Evidence remains accessible by export. |
| 214 | If names are unknown, opt into `include_available_property_keys: true`; it lists |
| 215 | the original keys per returned observation without unselected values. Keep each |
| 216 | row's node/observation identity paired when composing facts. |
| 217 | These rows select application-graph observations; semantic relationships and |
| 218 | semantic unknown records remain in the complete parent Evidence and trace tools. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
