Add RuntimeTargetDelegate::serializeStackTrace API (#54048)

Summary:

Changelog: [Internal]

Adds an engine-agnostic mechanism for serialising a previously captured stack trace as a CDP [`Runtime.StackTrace`](https://cdpstatus.reactnative.dev/devtools-protocol/tot/Runtime#type-StackTrace). This complements the existing `RuntimeTargetDelegate::captureStackTrace` method, which returns an opaque, engine-specific representation of a stack trace.

This can be used as a building block for implementing higher-level CDP message types like [`Network.Initiator`](https://cdpstatus.reactnative.dev/devtools-protocol/tot/Network#type-Initiator) within React Native, while keeping the underlying stack trace representation private to each engine.

NOTE: This diff includes an implementation for Hermes that duplicates logic from the Hermes codebase. Further up the stack, I have diffs to replace this with a new API to be provided by Hermes.

Differential Revision: D83754142

Author: motiz88

packages/react-native/ReactCommon/hermes/inspector-modern/chrome/HermesRuntimeTargetDelegate.cpp

@@ -78,6 +78,14 @@ class HermesRuntimeTargetDelegate::Impl final : public RuntimeTargetDelegate {
       return &hermesStackTrace_;
     }
 
+    const HermesStackTrace& operator*() const {
+      return hermesStackTrace_;
+    }
+
+    const HermesStackTrace* operator->() const {
+      return &hermesStackTrace_;
+    }
+
    private:
     HermesStackTrace hermesStackTrace_;
   };
@@ -216,6 +224,47 @@ class HermesRuntimeTargetDelegate::Impl final : public RuntimeTargetDelegate {
     return samplingProfileDelegate_->collectSamplingProfile();
   }
 
+  std::optional<folly::dynamic> serializeStackTrace(
+      const StackTrace& stackTrace) override {
+    if (auto* hermesStackTraceWrapper =
+            dynamic_cast<const HermesStackTraceWrapper*>(&stackTrace)) {
+      // The logic below is duplicated from
+      // facebook::hermes::cdp::message::makeCallFrames in
+      // hermes/cdp/MessageConverters.cpp (and rewritten to use Folly).
+      // TODO: Use a suitable Hermes API (D83560910 / D83560972 / D83562078) to
+      // serialize the stack trace to CDP-formatted JSON.
+      folly::dynamic stackTrace = folly::dynamic::object();
+      auto& hermesStackTrace = **hermesStackTraceWrapper;
+      if (hermesStackTrace.callFrameCount() > 0) {
+        folly::dynamic callFrames = folly::dynamic::array();
+        callFrames.reserve(hermesStackTrace.callFrameCount());
+        for (size_t i = 0, n = hermesStackTrace.callFrameCount(); i != n; i++) {
+          auto callFrame = hermesStackTrace.callFrameForIndex(i);
+          if (callFrame.location.fileId ==
+              facebook::hermes::debugger::kInvalidLocation) {
+            continue;
+          }
+          folly::dynamic callFrameObj = folly::dynamic::object();
+          callFrameObj["functionName"] = callFrame.functionName;
+          callFrameObj["scriptId"] = std::to_string(callFrame.location.fileId);
+          callFrameObj["url"] = callFrame.location.fileName;
+          if (callFrame.location.line !=
+              facebook::hermes::debugger::kInvalidLocation) {
+            callFrameObj["lineNumber"] = callFrame.location.line - 1;
+          }
+          if (callFrame.location.column !=
+              facebook::hermes::debugger::kInvalidLocation) {
+            callFrameObj["columnNumber"] = callFrame.location.column - 1;
+          }
+          callFrames.push_back(std::move(callFrameObj));
+        }
+        stackTrace["callFrames"] = std::move(callFrames);
+      }
+      return stackTrace;
+    }
+    return std::nullopt;
+  }
+
  private:
   HermesRuntimeTargetDelegate& delegate_;
   std::shared_ptr<HermesRuntime> runtime_;
@@ -311,6 +360,11 @@ HermesRuntimeTargetDelegate::collectSamplingProfile() {
   return impl_->collectSamplingProfile();
 }
 
+std::optional<folly::dynamic> HermesRuntimeTargetDelegate::serializeStackTrace(
+    const StackTrace& stackTrace) {
+  return impl_->serializeStackTrace(stackTrace);
+}
+
 #ifdef HERMES_ENABLE_DEBUGGER
 CDPDebugAPI& HermesRuntimeTargetDelegate::getCDPDebugAPI() {
   return impl_->getCDPDebugAPI();

packages/react-native/ReactCommon/hermes/inspector-modern/chrome/HermesRuntimeTargetDelegate.h

@@ -60,6 +60,9 @@ class HermesRuntimeTargetDelegate : public RuntimeTargetDelegate {
 
   tracing::RuntimeSamplingProfile collectSamplingProfile() override;
 
+  std::optional<folly::dynamic> serializeStackTrace(
+      const StackTrace& stackTrace) override;
+
  private:
   // We use the private implementation idiom to ensure this class has the same
   // layout regardless of whether HERMES_ENABLE_DEBUGGER is defined. The net

packages/react-native/ReactCommon/jsinspector-modern/FallbackRuntimeTargetDelegate.cpp

@@ -58,4 +58,10 @@ FallbackRuntimeTargetDelegate::collectSamplingProfile() {
       "Sampling Profiler capabilities are not supported for Runtime fallback");
 }
 
+std::optional<folly::dynamic>
+FallbackRuntimeTargetDelegate::serializeStackTrace(
+    const StackTrace& /*stackTrace*/) {
+  return std::nullopt;
+}
+
 } // namespace facebook::react::jsinspector_modern

packages/react-native/ReactCommon/jsinspector-modern/FallbackRuntimeTargetDelegate.h

@@ -46,6 +46,9 @@ class FallbackRuntimeTargetDelegate : public RuntimeTargetDelegate {
 
   tracing::RuntimeSamplingProfile collectSamplingProfile() override;
 
+  std::optional<folly::dynamic> serializeStackTrace(
+      const StackTrace& stackTrace) override;
+
  private:
   std::string engineDescription_;
 };

packages/react-native/ReactCommon/jsinspector-modern/RuntimeTarget.h

@@ -108,6 +108,14 @@ class RuntimeTargetDelegate {
    * Return recorded sampling profile for the previous sampling session.
    */
   virtual tracing::RuntimeSamplingProfile collectSamplingProfile() = 0;
+
+  /**
+   * \returns a JSON representation of the given stack trace, conforming to the
+   * @cdp Runtime.StackTrace type, if the runtime supports it. Otherwise,
+   * returns std::nullopt.
+   */
+  virtual std::optional<folly::dynamic> serializeStackTrace(
+      const StackTrace& stackTrace) = 0;
 };
 
 /**

packages/react-native/ReactCommon/jsinspector-modern/tests/InspectorMocks.h

@@ -169,6 +169,11 @@ class MockRuntimeTargetDelegate : public RuntimeTargetDelegate {
       collectSamplingProfile,
       (),
       (override));
+  MOCK_METHOD(
+      std::optional<folly::dynamic>,
+      serializeStackTrace,
+      (const StackTrace& stackTrace),
+      (override));
 
   inline MockRuntimeTargetDelegate() {
     using namespace testing;

packages/react-native/ReactCommon/jsinspector-modern/tests/JsiIntegrationTest.cpp

@@ -893,6 +893,88 @@ TYPED_TEST(JsiIntegrationHermesTest, ReleaseRemoteObjectGroup) {
                                })");
 }
 
+// A low-level test for captureStackTrace and serializeStackTrace in
+// HermesRuntimeTargetDelegate. This functionality is not directly exposed
+// to user code, but serves as a building block for higher-level CDP domains.
+TYPED_TEST(JsiIntegrationHermesTest, testCaptureAndSerializeStackTrace) {
+  auto& runtimeTargetDelegate = this->dangerouslyGetRuntimeTargetDelegate();
+  auto& runtime = this->dangerouslyGetRuntime();
+  runtime.global().setProperty(
+      runtime,
+      "captureCdpStackTrace",
+      jsi::Function::createFromHostFunction(
+          runtime,
+          jsi::PropNameID::forAscii(runtime, "captureCdpStackTrace"),
+          0,
+          [&runtimeTargetDelegate](
+              jsi::Runtime& rt,
+              const jsi::Value& /* thisVal */,
+              const jsi::Value* /* args */,
+              size_t /* count */) -> jsi::Value {
+            auto stackTraceDynamic = runtimeTargetDelegate.serializeStackTrace(
+                *runtimeTargetDelegate.captureStackTrace(rt));
+            if (!stackTraceDynamic.has_value()) {
+              return jsi::Value::undefined();
+            }
+            return jsi::String::createFromUtf8(
+                rt, folly::toJson(*stackTraceDynamic));
+          }));
+
+  this->connect();
+
+  InSequence s;
+
+  this->expectMessageFromPage(JsonEq(R"({
+                                         "id": 1,
+                                         "result": {}
+                                       })"));
+  this->toPage_->sendMessage(R"({
+                                 "id": 1,
+                                 "method": "Debugger.enable"
+                               })");
+
+  auto scriptInfo = this->expectMessageFromPage(JsonParsed(AllOf(
+      AtJsonPtr("/method", "Debugger.scriptParsed"),
+      AtJsonPtr("/params/url", "stackTraceTest.js"))));
+
+  auto stackTrace = this->eval(R"( // line 0
+    function inner() { // line 1
+      return globalThis.captureCdpStackTrace(); // line 2
+    } // line 3
+    function outer() { // line 4
+      return inner(); // line 5
+    } // line 6
+    outer(); // line 7
+    //# sourceURL=stackTraceTest.js
+  )")
+                        .getString(runtime)
+                        .utf8(runtime);
+
+  ASSERT_TRUE(scriptInfo->has_value());
+
+  EXPECT_THAT(
+      stackTrace,
+      JsonParsed(AllOf(
+          AtJsonPtr("/callFrames/0/functionName", "inner"),
+          AtJsonPtr(
+              "/callFrames/0/scriptId",
+              scriptInfo->value()["params"]["scriptId"]),
+          AtJsonPtr("/callFrames/0/lineNumber", 2),
+          AtJsonPtr("/callFrames/0/columnNumber", 44),
+          AtJsonPtr("/callFrames/1/functionName", "outer"),
+          AtJsonPtr(
+              "/callFrames/1/scriptId",
+              scriptInfo->value()["params"]["scriptId"]),
+          AtJsonPtr("/callFrames/1/lineNumber", 5),
+          AtJsonPtr("/callFrames/1/columnNumber", 18),
+          AtJsonPtr("/callFrames/2/functionName", "global"),
+          AtJsonPtr(
+              "/callFrames/2/scriptId",
+              scriptInfo->value()["params"]["scriptId"]),
+          AtJsonPtr("/callFrames/2/lineNumber", 7),
+          AtJsonPtr("/callFrames/2/columnNumber", 9))));
+}
+
 #pragma endregion // AllHermesVariants
 
 } // namespace facebook::react::jsinspector_modern

packages/react-native/ReactCommon/jsinspector-modern/tests/JsiIntegrationTest.h

@@ -156,6 +156,14 @@ class JsiIntegrationPortableTestBase : public ::testing::Test,
     return result;
   }
 
+  RuntimeTargetDelegate& dangerouslyGetRuntimeTargetDelegate() {
+    return engineAdapter_->getRuntimeTargetDelegate();
+  }
+
+  jsi::Runtime& dangerouslyGetRuntime() {
+    return engineAdapter_->getRuntime();
+  }
+
   std::shared_ptr<HostTarget> page_;
   InstanceTarget* instance_{};
   RuntimeTarget* runtimeTarget_{};