rea/docs/javascript-application-workflows.md

Cross-layer JavaScript application workflows

REA derives a complete reachable feature trace from one authenticated JavaScript Application Graph and compares two authenticated graph versions. The MCP tools are inspect_analysis_view, trace_application_feature, trace_javascript_semantics, compare_application_versions, compare_source_to_bundle, and compare_javascript_export_shapes; their CLI equivalents use the same names with hyphens. inspect_analysis_view projects a summary, module page, typed module references, or one module from already completed application Evidence; it does not walk relationships.

inspect_analysis_view also projects retained inspect_binary_layout Evidence. The remaining workflows consume Evidence produced by analyze_javascript_application or reconcile_javascript_runtime. They do not read an artifact, execute application code, attach to a process, or open a native-analysis provider. Static artifact observations, passive runtime observations, relationship inferences, and unknown or unavailable facts retain their original graph authority.

analyze_javascript_application Evidence retains the structural JavaScript Application Graph and a separate semantic relation graph bound to the same root artifact digest and structural graph ID. Semantic tracing requires the semantic relation graph and reports when it is unavailable rather than treating missing data as an empty graph.

Worker progress reports the source path and last observed parse, static, semantic, projection or transfer stage. These notifications do not measure stage CPU/time or establish the root cause of a slow or incomplete analysis. Semantic projection limits bound retained output, not upstream analysis work.

Explicit TypeScript import type and export type declarations remain source facts and do not create runtime import or export relationships. Type export names are reported separately from value export names. Inline type specifiers can leave an empty import or re-export with side effects under verbatimModuleSyntax; REA retains those dependency candidates and reports the unavailable compiler options rather than assuming the dependency is erased.

The semantic graph wire format stores shared non-location provenance once in its required evidence_contexts table. Each node, relation, fingerprint, and unknown retains its exact evidence.location and names the owning context with evidence.context_id. This is a breaking representation change: consumers reading fields such as evidence.authority must look up the context by ID and combine its fields with the fact's location. Semantic trace results include the canonical context subset referenced by their returned facts, so those facts remain self-contained in the response.

Content-deduplicated module references match every retained observation path. A path-filtered reference reports the caller-selected path while keeping its shared node identity. Item selection also accepts any retained path when it identifies one module; if several module kinds share that path, select the reported node_id. Node-ID selection uses the stable representative path.

Retained module facts

For canonical identities and retained source-range counts, query the existing inspect_analysis_view tool with a typed module-reference projection:

{
  "source": {
    "kind": "retained-evidence",
    "evidence_id": "ev_ACTUAL_PARENT_ID"
  },
  "view": {
    "kind