fix: doclinks don't select a default platform (#1882)

Previously this would default to Android, which isn't intuitive. Also
fixed some links to be more specific. The new api is:

  link.docs(<path>, <platform>)

For platforms your choices are:
 - ios
 - android
 - none -> drop the platform parameter if the docs don't have any
   platform specific relevance.
 - inherit -> use this if you have to `link.setPlatform` before hitting
   a cli-command (will assert and fail at runtime if you haven't). See
   the `upgrading` command for an example.

packages/cli-doctor/src/tools/healthchecks/adb.ts

@@ -63,10 +63,9 @@ export default {
     } catch (e) {
       return logManualInstallation({
         healthcheck: 'Adb',
-        url: link.docs('running-on-device', {
+        url: link.docs('running-on-device', 'android', {
           hash: hash,
           guide: 'native',
-          platform: 'android',
         }),
       });
     }

packages/cli-doctor/src/tools/healthchecks/androidSDK.ts

@@ -182,10 +182,9 @@ export default {
 
     return logManualInstallation({
       healthcheck: 'Android SDK',
-      url: link.docs('environment-setup', {
+      url: link.docs('environment-setup', 'android', {
         hash: 'android-sdk',
         guide: 'native',
-        platform: 'android',
       }),
     });
   },

packages/cli-doctor/src/tools/healthchecks/androidStudio.ts

@@ -76,10 +76,9 @@ export default {
 
     return logManualInstallation({
       healthcheck: 'Android Studio',
-      url: link.docs('environment-setup', {
+      url: link.docs('environment-setup', 'android', {
         hash: 'android-studio',
         guide: 'native',
-        platform: 'android',
       }),
     });
   },

packages/cli-doctor/src/tools/healthchecks/jdk.ts

@@ -61,10 +61,9 @@ export default {
     loader.fail();
     logManualInstallation({
       healthcheck: 'JDK',
-      url: link.docs('environment-setup', {
+      url: link.docs('environment-setup', 'android', {
         hash: 'jdk-studio',
         guide: 'native',
-        platform: 'android',
       }),
     });
   },

packages/cli-doctor/src/tools/healthchecks/ruby.ts

@@ -174,10 +174,9 @@ export default {
 
     logManualInstallation({
       healthcheck: 'Ruby',
-      url: link.docs('environment-setup', {
+      url: link.docs('environment-setup', 'ios', {
         hash: 'ruby',
         guide: 'native',
-        platform: 'ios',
       }),
     });
   },

packages/cli-doctor/src/tools/installPods.ts

@@ -44,6 +44,8 @@ async function runPodInstall(
       throw new CLIError(
         `Looks like your iOS environment is not properly set. Please go to ${link.docs(
           'environment-setup',
+          'ios',
+          {guide: 'native'},
         )} and follow the React Native CLI QuickStart guide for macOS and iOS.`,
       );
     }

packages/cli-doctor/src/tools/runBundleInstall.ts

@@ -14,6 +14,8 @@ async function runBundleInstall(loader: Loader) {
     throw new CLIError(
       `Looks like your iOS environment is not properly set. Please go to ${link.docs(
         'environment-setup',
+        'ios',
+        {guide: 'native'},
       )} and follow the React Native CLI QuickStart guide for macOS and iOS.`,
     );
   }

packages/cli-platform-android/src/commands/runAndroid/runOnAllDevices.ts

@@ -140,10 +140,9 @@ function createInstallError(error: Error & {stderr: string}) {
     )}."`;
   } else if (stderr.includes('requires Java')) {
     message = `Looks like your Android environment is not properly set. Please go to ${chalk.dim.underline(
-      link.docs('environment-setup', {
+      link.docs('environment-setup', 'android', {
         hash: 'jdk-studio',
         guide: 'native',
-        platform: 'android',
       }),
     )} and follow the React Native CLI QuickStart guide to install the compatible version of JDK.`;
   }

packages/cli-tools/src/__tests__/doclink.test.ts

@@ -10,7 +10,7 @@ describe('link', () => {
     mockPlatform.mockReturnValueOnce('darwin');
     link.setPlatform('android');
 
-    const url = new URL(link.docs('environment-setup')).toString();
+    const url = new URL(link.docs('environment-setup', 'inherit')).toString();
     expect(url).toMatch(/os=macos/);
     expect(url).toMatch(/platform=android/);
     expect(url).toEqual(
@@ -19,34 +19,47 @@ describe('link', () => {
 
     // Handles a change of os
     mockPlatform.mockReturnValueOnce('win32');
-    expect(link.docs('environment-setup')).toMatch(/os=windows/);
+    expect(link.docs('environment-setup', 'inherit')).toMatch(/os=windows/);
 
     // Handles a change of platform
     link.setPlatform('ios');
-    expect(link.docs('environment-setup')).toMatch(/platform=ios/);
+    expect(link.docs('environment-setup', 'inherit')).toMatch(/platform=ios/);
+
+    // Handles cases where we don't need a platform
+    expect(link.blog('2019/11/18/react-native-doctor', 'none')).not.toMatch(
+      /platform=/,
+    );
   });
 
   it('preserves anchor-links', () => {
-    expect(link.docs('environment-setup', 'ruby')).toMatch(/#ruby/);
+    expect(link.docs('environment-setup', 'inherit', 'ruby')).toMatch(/#ruby/);
   });
 
   describe('overrides', () => {
     afterAll(() => link.setVersion(null));
     it.each([
       [{hash: 'ruby'}, /#ruby/],
       [{hash: 'ruby', os: 'linux'}, /os=linux/],
-      [{platform: 'ios'}, /platform=ios/],
       [{'extra stuff': 'here?ok'}, /extra\+stuff=here%3Fok/],
     ])("link.doc('environment-setup, %o) -> %o", (param, re) => {
-      expect(link.docs('environment-setup', param)).toMatch(re);
+      expect(link.docs('environment-setup', 'none', param)).toMatch(re);
+    });
+  });
+
+  describe('enforces platform inheritance', () => {
+    it("asserts on not setting the platform for link.docs('foo', 'inherit')", () => {
+      link.setPlatform(null);
+      expect(() => {
+        link.docs('foobar', 'inherit');
+      }).toThrow(/link\.setPlatform/);
     });
   });
 
   describe('versions', () => {
     afterAll(() => link.setVersion(null));
     it('supports linking to a specific version of React Native', () => {
       link.setVersion('0.71');
-      expect(link.docs('environment-setup', 'ruby')).toEqual(
+      expect(link.docs('environment-setup', 'ios', 'ruby')).toEqual(
         expect.stringContaining(
           'https://reactnative.dev/docs/0.71/environment-setup',
         ),

packages/cli-tools/src/doclink.ts

@@ -1,7 +1,11 @@
 import os from 'os';
 import assert from 'assert';
 
-type Platforms = 'android' | 'ios';
+type Platforms =
+  | 'android'
+  | 'ios'
+  | 'inherit' // Expect the platform to be defined before this link is called with the link.setPlatform()
+  | 'none'; // No platform specific documentation
 
 export function getOS(): string {
   // Using os.platform instead of process.platform so we can test more easily. Once jest upgrades
@@ -23,12 +27,11 @@ export function getOS(): string {
   }
 }
 
-let _platform: Platforms = 'android';
+let _platform: Platforms | null = null;
 let _version: string | undefined;
 
 interface Overrides {
   os?: string;
-  platform?: string;
   hash?: string;
   version?: string;
 }
@@ -43,6 +46,7 @@ interface Other {
 function doclink(
   section: string,
   path: string,
+  platform: Platforms,
   hashOrOverrides?: string | (Overrides & Other),
 ): string {
   const url = new URL('https://reactnative.dev/');
@@ -54,19 +58,30 @@ function doclink(
   const version =
     isObj && hashOrOverrides.version ? hashOrOverrides.version : _version;
   const OS = isObj && hashOrOverrides.os ? hashOrOverrides.os : getOS();
-  const platform =
-    isObj && hashOrOverrides.platform ? hashOrOverrides.platform : _platform;
 
   url.pathname = _version
     ? `${section}/${version}/${path}`
     : `${section}/${path}`;
 
   url.searchParams.set('os', OS);
-  url.searchParams.set('platform', platform);
+
+  if (platform === 'inherit') {
+    assert.ok(
+      _platform !== null,
+      `Please report this CLI error:  link.setPlatform('ios'|'android'|'none') was expected to be set before using link.${section}(${path}, 'inherit').`,
+    );
+  }
+
+  const plat: Platforms =
+    platform === 'inherit' ? (_platform as Platforms) : platform ?? _platform;
+
+  if (plat !== 'none') {
+    url.searchParams.set('platform', plat);
+  }
 
   if (isObj) {
     const otherKeys = Object.keys(hashOrOverrides).filter(
-      (key) => !['hash', 'version', 'os', 'platform'].includes(key),
+      (key) => !['hash', 'version', 'os'].includes(key),
     );
     for (let key of otherKeys) {
       url.searchParams.set(key, hashOrOverrides[key]);
@@ -77,7 +92,7 @@ function doclink(
     assert.doesNotMatch(
       hash,
       /#/,
-      "Anchor links should be written withou a '#'",
+      "Anchor links should be written without a '#'",
     );
     url.hash = hash;
   }

packages/cli-tools/src/releaseChecker/printNewRelease.ts

@@ -21,7 +21,7 @@ export default function printNewRelease(
   logger.info(`Diff: ${chalk.dim.underline(latestRelease.diffUrl)}`);
   logger.info(
     `For more info, check out "${chalk.dim.underline(
-      link.docs('upgrading'),
+      link.docs('upgrading', 'inherit'),
     )}".`,
   );