fix(cli): automatically compose source maps for Hermes bundle

.changeset/afraid-suns-live.md

@@ -0,0 +1,5 @@
+---
+"@rnx-kit/tools-react-native": patch
+---
+
+Allow importing `metro-source-map` via `metro`

.changeset/red-turkeys-trade.md

@@ -0,0 +1,5 @@
+---
+"@rnx-kit/cli": patch
+---
+
+Automatically compose source maps of the JS and Hermes bytecode bundles

packages/cli/src/bundle/hermes.ts

@@ -1,6 +1,7 @@
 import type { HermesOptions } from "@rnx-kit/config";
 import { error, info } from "@rnx-kit/console";
 import { findPackageDependencyDir } from "@rnx-kit/tools-node/package";
+import { requireModuleFromMetro } from "@rnx-kit/tools-react-native/metro";
 import { spawnSync } from "child_process";
 import * as fs from "fs";
 import * as os from "os";
@@ -57,10 +58,6 @@ function getOutput(args: string[]): string | null {
   return null;
 }
 
-function isSourceMapFlag(flag: string): boolean {
-  return flag === "-source-map" || flag.startsWith("-source-map=");
-}
-
 export function emitBytecode(
   input: string,
   sourcemap: string | undefined,
@@ -90,15 +87,28 @@ export function emitBytecode(
     args.push("-out", output);
   }
 
-  if (sourcemap && !args.some(isSourceMapFlag)) {
-    args.push("-source-map", sourcemap);
-  }
-
   args.push(input);
 
   info("Emitting bytecode to:", output);
   const result = spawnSync(cmd, args, { stdio: "inherit" });
   if (result.status !== 0) {
     throw result.error;
   }
+
+  if (sourcemap && args.includes("-output-source-map")) {
+    const outputMap = output + ".map";
+    info(`Combining source maps: ${sourcemap} + ${outputMap}`);
+
+    const options = { encoding: "utf-8" } as const;
+    const packagerSourcemap = JSON.parse(fs.readFileSync(sourcemap, options));
+    const compilerSourcemap = JSON.parse(fs.readFileSync(outputMap, options));
+
+    // `composeSourceMaps` was introduced in 0.56 — see
+    // https://github.com/facebook/metro/commit/6017085bdad96ca5cec39d50038eb5622ce1097b
+    // @ts-expect-error Property 'composeSourceMaps' does not exist
+    const { composeSourceMaps } = requireModuleFromMetro("metro-source-map");
+
+    const composed = composeSourceMaps([packagerSourcemap, compilerSourcemap]);
+    fs.writeFileSync(outputMap, JSON.stringify(composed));
+  }
 }

packages/tools-react-native/package.json

@@ -59,6 +59,7 @@
     "metro-config": "^0.76.5",
     "metro-core": "^0.76.5",
     "metro-resolver": "^0.76.5",
+    "metro-source-map": "^0.76.5",
     "prettier": "^3.0.0",
     "typescript": "^5.0.0"
   },

packages/tools-react-native/src/metro.ts

@@ -10,7 +10,8 @@ type MetroImport =
   | typeof import("metro/src/shared/output/bundle")
   | typeof import("metro-config")
   | typeof import("metro-core")
-  | typeof import("metro-resolver");
+  | typeof import("metro-resolver")
+  | typeof import("metro-source-map");
 
 type MetroModule =
   | "metro"
@@ -19,7 +20,8 @@ type MetroModule =
   | "metro/src/shared/output/bundle"
   | "metro-config"
   | "metro-core"
-  | "metro-resolver";
+  | "metro-resolver"
+  | "metro-source-map";
 
 function resolveFrom(name: string, startDir: string): string | undefined {
   return findPackageDependencyDir(name, {
@@ -110,6 +112,11 @@ export function requireModuleFromMetro(
   fromDir?: string
 ): typeof import("metro-resolver");
 
+export function requireModuleFromMetro(
+  moduleName: "metro-source-map",
+  fromDir?: string
+): typeof import("metro-source-map");
+
 /**
  * Imports specified module starting from the installation directory of the
  * currently used `metro` version.

yarn.lock

@@ -4386,6 +4386,7 @@ __metadata:
     metro-config: ^0.76.5
     metro-core: ^0.76.5
     metro-resolver: ^0.76.5
+    metro-source-map: ^0.76.5
     prettier: ^3.0.0
     typescript: ^5.0.0
   languageName: unknown
@@ -10638,7 +10639,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"metro-source-map@npm:0.76.8, metro-source-map@npm:^0.76.8":
+"metro-source-map@npm:0.76.8, metro-source-map@npm:^0.76.5, metro-source-map@npm:^0.76.8":
   version: 0.76.8
   resolution: "metro-source-map@npm:0.76.8"
   dependencies: