runBuild: Support specifying bundleOut/sourceMapOut

Summary:
Currently Metro's `runBuild` allows saving bundle and source maps to disk via a single `out` argument, which always appends a `.js` extension for bundles (unless `out` already ends with `.js`) and `.map` for source maps.

This means it can't currently be used to implement React Native CLI's `bundle` command, because RN uses `.jsbundle` extension by convention (eg, [here](https://github.com/facebook/react-native/blob/5d7f35cd7c912333987ca82774734dba3bd48716/packages/react-native/scripts/react-native-xcode.sh#L108).

This is an additive API change to allow `bundleOut` and `sourceMapOut` to specify full paths. This also allows us to fix the `react-native/core-cli-utils` todo [here](https://github.com/facebook/react-native/blob/5d7f35cd7c912333987ca82774734dba3bd48716/packages/core-cli-utils/src/private/app.js#L133).

```
 - **[Feature]** `runBuild`: Add optional `bundleOut` and `sourceMapOut` arguments to exactly specify output paths.
```

Reviewed By: huntie

Differential Revision: D74397776

fbshipit-source-id: a2cbe5df1a553447d60d6cca5138d318be78dc1f

Author: robhogan

docs/GettingStarted.md

@@ -129,15 +129,17 @@ Given a configuration and a set of options that you would typically pass to a se
 <!-- TODO(ives): Decide whether we need to show this to the user  * `output (boolean)` -->
 
 * `assets (boolean)`: Whether to include the assets in the result.
+* `bundleOut (string)`: Path to save the bundle. No extension will be added.
 * `dev (boolean)`: Create a development version of the build (`process.env.NODE_ENV = 'development'`).
 * `entry (string)`: Pointing to the entry file to bundle.
 * `onBegin (Function)`: Called when the bundling starts.
 * `onComplete (Function)`: Called when the bundling finishes.
 * `onProgress (Function)`: Called during the bundle, every time there's new information available about the module count/progress.
 * `minify (boolean)`: Whether Metro should minify the bundle.
-* `out (string)`: Path to the output bundle.
+* `out (string)`: Shorthand path to the output bundle and source map. A `.js` extension will be added (if not given) for the bundle and `.map` for the source map. Customize with `bundleOut` / `sourceMapOut`.
 * `platform ('web' | 'android' | 'ios')`: Which platform to bundle for if a list of platforms is provided.
 * `sourceMap (boolean)`: Whether Metro should generate source maps.
+* `sourceMapOut (string)`: Where to save the source map, if `sourceMap == true`. No extension will be added.
 * `sourceMapUrl (string)`: URL where the source map can be found. It defaults to the same same URL as the bundle, but changing the extension from `.bundle` to `.map`. When `inlineSourceMap` is `true`, this property has no effect.
 
 ```js

packages/metro/src/index.flow.js

@@ -50,6 +50,7 @@ const {
 } = require('metro-config');
 const {Terminal} = require('metro-core');
 const net = require('net');
+const nullthrows = require('nullthrows');
 const {parse} = require('url');
 
 type MetroMiddleWare = {
@@ -97,6 +98,8 @@ export type RunBuildOptions = {
   assets?: boolean,
   dev?: boolean,
   out?: string,
+  bundleOut?: string,
+  sourceMapOut?: string,
   onBegin?: () => void,
   onComplete?: () => void,
   onProgress?: (transformedFileCount: number, totalFileCount: number) => void,
@@ -394,6 +397,8 @@ exports.runBuild = async (
     minify = true,
     output = outputBundle,
     out,
+    bundleOut,
+    sourceMapOut,
     platform = 'web',
     sourceMap = false,
     sourceMapUrl,
@@ -437,10 +442,14 @@ exports.runBuild = async (
       onComplete();
     }
 
-    if (out) {
-      const bundleOutput = out.replace(/(\.js)?$/, '.js');
+    if (out || bundleOut) {
+      const bundleOutput =
+        bundleOut ?? nullthrows(out).replace(/(\.js)?$/, '.js');
+
       const sourcemapOutput =
-        sourceMap === false ? undefined : out.replace(/(\.js)?$/, '.map');
+        sourceMap === false
+          ? undefined
+          : sourceMapOut ?? out?.replace(/(\.js)?$/, '.map');
 
       const outputOptions: OutputOptions = {
         bundleOutput,

packages/metro/src/integration_tests/__tests__/build-test.js

@@ -90,6 +90,36 @@ test('build a simple bundle with assets', async () => {
   ]);
 });
 
+test('allows specifying paths to save bundle and maps', async () => {
+  const config = await Metro.loadConfig({
+    config: require.resolve('../metro.config.js'),
+  });
+  const mockSave = jest.fn();
+
+  await Metro.runBuild(config, {
+    entry: 'TestBundle.js',
+    output: {
+      ...require('../../shared/output/bundle'),
+      save: mockSave,
+    },
+    sourceMapOut: 'TestBundle.custommap',
+    sourceMap: true,
+    bundleOut: 'TestBundle.jsbundle',
+  });
+
+  expect(mockSave).toBeCalledWith(
+    {
+      code: expect.any(String),
+      map: expect.any(String),
+    },
+    expect.objectContaining({
+      bundleOutput: 'TestBundle.jsbundle',
+      sourcemapOutput: 'TestBundle.custommap',
+    }),
+    expect.any(Function),
+  );
+});
+
 test('(unstable) allows specifying a transform profile', async () => {
   const config = await Metro.loadConfig({
     config: require.resolve('../metro.config.js'),