parseHookNames.js

/* global chrome */

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @flow
 */

import {parse} from '@babel/parser';
import {enableHookNameParsing} from 'react-devtools-feature-flags';
import LRU from 'lru-cache';
import {SourceMapConsumer} from 'source-map';
import {getHookName, isNonDeclarativePrimitiveHook} from './astUtils';
import {areSourceMapsAppliedToErrors} from './ErrorTester';
import {__DEBUG__} from 'react-devtools-shared/src/constants';

import type {
  HooksNode,
  HookSource,
  HooksTree,
} from 'react-debug-tools/src/ReactDebugHooks';
import type {HookNames, LRUCache} from 'react-devtools-shared/src/types';
import type {Thenable} from 'shared/ReactTypes';
import type {SourceConsumer, SourceMap} from './astUtils';

const SOURCE_MAP_REGEX = / ?sourceMappingURL=([^\s'"]+)/gm;
const ABSOLUTE_URL_REGEX = /^https?:\/\//i;
const MAX_SOURCE_LENGTH = 100_000_000;

type AST = mixed;

type HookSourceData = {|
  // Generated by react-debug-tools.
  hookSource: HookSource,

  // AST for original source code; typically comes from a consumed source map.
  originalSourceAST: AST | null,

  // Source code (React components or custom hooks) containing primitive hook calls.
  // If no source map has been provided, this code will be the same as runtimeSourceCode.
  originalSourceCode: string | null,

  // Compiled code (React components or custom hooks) containing primitive hook calls.
  runtimeSourceCode: string | null,

  // APIs from source-map for parsing source maps (if detected).
  sourceConsumer: SourceConsumer | null,

  // External URL of source map.
  // Sources without source maps (or with inline source maps) won't have this.
  sourceMapURL: string | null,

  // Parsed source map object.
  sourceMapContents: SourceMap | null,
|};

type CachedMetadata = {|
  originalSourceAST: AST,
  originalSourceCode: string,
  sourceConsumer: SourceConsumer | null,
|};

// On large trees, encoding takes significant time.
// Try to reuse the already encoded strings.
const fileNameToMetadataCache: LRUCache<string, CachedMetadata> = new LRU({
  max: 50,
  dispose: (fileName: string, metadata: CachedMetadata) => {
    if (__DEBUG__) {
      console.log(
        'fileNameToHookSourceData.dispose() Evicting cached metadata for "' +
          fileName +
          '"',
      );
    }

    const sourceConsumer = metadata.sourceConsumer;
    if (sourceConsumer !== null) {
      sourceConsumer.destroy();
    }
  },
});

export default async function parseHookNames(
  hooksTree: HooksTree,
): Thenable<HookNames | null> {
  if (!enableHookNameParsing) {
    return Promise.resolve(null);
  }

  const hooksList: Array<HooksNode> = [];
  flattenHooksList(hooksTree, hooksList);

  if (__DEBUG__) {
    console.log('parseHookNames() hooksList:', hooksList);
  }

  // Gather the unique set of source files to load for the built-in hooks.
  const fileNameToHookSourceData: Map<string, HookSourceData> = new Map();
  for (let i = 0; i < hooksList.length; i++) {
    const hook = hooksList[i];

    const hookSource = hook.hookSource;
    if (hookSource == null) {
      // Older versions of react-debug-tools don't include this information.
      // In this case, we can't continue.
      throw Error('Hook source code location not found.');
    }

    const fileName = hookSource.fileName;
    if (fileName == null) {
      throw Error('Hook source code location not found.');
    } else {
      if (!fileNameToHookSourceData.has(fileName)) {
        const hookSourceData: HookSourceData = {
          hookSource,
          originalSourceAST: null,
          originalSourceCode: null,
          runtimeSourceCode: null,
          sourceConsumer: null,
          sourceMapURL: null,
          sourceMapContents: null,
        };

        // If we've already loaded source/source map info for this file,
        // we can skip reloading it (and more importantly, re-parsing it).
        const metadata = fileNameToMetadataCache.get(fileName);
        if (metadata != null) {
          if (__DEBUG__) {
            console.groupCollapsed(
              'parseHookNames() Found cached metadata for file "' +
                fileName +
                '"',
            );
            console.log(metadata);
            console.groupEnd();
          }

          hookSourceData.originalSourceAST = metadata.originalSourceAST;
          hookSourceData.originalSourceCode = metadata.originalSourceCode;
          hookSourceData.sourceConsumer = metadata.sourceConsumer;
        }

        fileNameToHookSourceData.set(fileName, hookSourceData);
      }
    }
  }

  return loadSourceFiles(fileNameToHookSourceData)
    .then(() => extractAndLoadSourceMaps(fileNameToHookSourceData))
    .then(() => parseSourceAST(fileNameToHookSourceData))
    .then(() => updateLruCache(fileNameToHookSourceData))
    .then(() => findHookNames(hooksList, fileNameToHookSourceData));
}

function decodeBase64String(encoded: string): Object {
  if (typeof atob === 'function') {
    return atob(encoded);
  } else if (
    typeof Buffer !== 'undefined' &&
    Buffer !== null &&
    typeof Buffer.from === 'function'
  ) {
    return Buffer.from(encoded, 'base64');
  } else {
    throw Error('Cannot decode base64 string');
  }
}

function extractAndLoadSourceMaps(
  fileNameToHookSourceData: Map<string, HookSourceData>,
): Promise<*> {
  const promises = [];
  fileNameToHookSourceData.forEach(hookSourceData => {
    if (hookSourceData.originalSourceAST !== null) {
      // Use cached metadata.
      return;
    }

    const runtimeSourceCode = ((hookSourceData.runtimeSourceCode: any): string);
    const sourceMappingURLs = runtimeSourceCode.match(SOURCE_MAP_REGEX);
    if (sourceMappingURLs == null) {
      // Maybe file has not been transformed; we'll try to parse it as-is in parseSourceAST().

      if (__DEBUG__) {
        console.log('extractAndLoadSourceMaps() No source map found');
      }
    } else {
      for (let i = 0; i < sourceMappingURLs.length; i++) {
        const sourceMappingURL = sourceMappingURLs[i];
        const index = sourceMappingURL.indexOf('base64,');
        if (index >= 0) {
          // Web apps like Code Sandbox embed multiple inline source maps.
          // In this case, we need to loop through and find the right one.
          // We may also need to trim any part of this string that isn't based64 encoded data.
          const trimmed = ((sourceMappingURL.match(
            /base64,([a-zA-Z0-9+\/=]+)/,
          ): any): Array<string>)[1];
          const decoded = decodeBase64String(trimmed);
          const parsed = JSON.parse(decoded);

          if (__DEBUG__) {
            console.groupCollapsed(
              'extractAndLoadSourceMaps() Inline source map',
            );
            console.log(parsed);
            console.groupEnd();
          }

          // Hook source might be a URL like "https://4syus.csb.app/src/App.js"
          // Parsed source map might be a partial path like "src/App.js"
          const fileName = ((hookSourceData.hookSource.fileName: any): string);
          const match = parsed.sources.find(
            source =>
              source === 'Inline Babel script' || fileName.includes(source),
          );
          if (match) {
            hookSourceData.sourceMapContents = parsed;
            break;
          }
        } else {
          if (sourceMappingURLs.length > 1) {
            console.warn(
              'More than one external source map detected in the source file',
            );
          }

          let url = sourceMappingURLs[0].split('=')[1];
          if (ABSOLUTE_URL_REGEX.test(url)) {
            const baseURL = url.slice(0, url.lastIndexOf('/'));
            url = `${baseURL}/${url}`;

            if (!isValidUrl(url)) {
              throw new Error(`Invalid source map URL "${url}"`);
            }
          }

          hookSourceData.sourceMapURL = url;

          if (__DEBUG__) {
            console.log(
              'extractAndLoadSourceMaps() External source map "' + url + '"',
            );
          }

          promises.push(
            fetchFile(url).then(sourceMapContents => {
              hookSourceData.sourceMapContents = JSON.parse(sourceMapContents);
            }),
          );
          break;
        }
      }
    }
  });
  return Promise.all(promises);
}

function fetchFile(url: string): Promise<string> {
  return new Promise((resolve, reject) => {
    fetch(url).then(response => {
      if (response.ok) {
        response
          .text()
          .then(text => {
            resolve(text);
          })
          .catch(error => {
            reject(null);
          });
      } else {
        reject(null);
      }
    });
  });
}

function findHookNames(
  hooksList: Array<HooksNode>,
  fileNameToHookSourceData: Map<string, HookSourceData>,
): HookNames {
  const map: HookNames = new Map();

  hooksList.map(hook => {
    if (isNonDeclarativePrimitiveHook(hook)) {
      if (__DEBUG__) {
        console.log('findHookNames() Non declarative primitive hook');
      }

      // Not all hooks have names (e.g. useEffect or useLayoutEffect)
      return null;
    }

    // We already guard against a null HookSource in parseHookNames()
    const hookSource = ((hook.hookSource: any): HookSource);
    const fileName = hookSource.fileName;
    if (!fileName) {
      return null; // Should not be reachable.
    }

    const hookSourceData = fileNameToHookSourceData.get(fileName);
    if (!hookSourceData) {
      return null; // Should not be reachable.
    }

    const {lineNumber, columnNumber} = hookSource;
    if (!lineNumber || !columnNumber) {
      return null; // Should not be reachable.
    }

    const sourceConsumer = hookSourceData.sourceConsumer;

    let originalSourceLineNumber;
    if (areSourceMapsAppliedToErrors() || !sourceConsumer) {
      // Either the current environment automatically applies source maps to errors,
      // or the current code had no source map to begin with.
      // Either way, we don't need to convert the Error stack frame locations.
      originalSourceLineNumber = lineNumber;
    } else {
      originalSourceLineNumber = sourceConsumer.originalPositionFor({
        line: lineNumber,
        column: columnNumber,
      }).line;
    }

    if (__DEBUG__) {
      console.log(
        'findHookNames() mapped line number',
        lineNumber,
        'to',
        originalSourceLineNumber,
      );
    }

    if (originalSourceLineNumber === null) {
      return null;
    }

    const name = getHookName(
      hook,
      hookSourceData.originalSourceAST,
      ((hookSourceData.originalSourceCode: any): string),
      ((originalSourceLineNumber: any): number),
    );

    if (__DEBUG__) {
      console.log('findHookNames() Found name "' + (name || '-') + '"');
    }

    map.set(hook, name);
  });

  return map;
}

function isValidUrl(possibleURL: string): boolean {
  try {
    // eslint-disable-next-line no-new
    new URL(possibleURL);
  } catch (_) {
    return false;
  }
  return true;
}

function loadSourceFiles(
  fileNameToHookSourceData: Map<string, HookSourceData>,
): Promise<*> {
  const promises = [];
  fileNameToHookSourceData.forEach((hookSourceData, fileName) => {
    promises.push(
      fetchFile(fileName).then(runtimeSourceCode => {
        if (runtimeSourceCode.length > MAX_SOURCE_LENGTH) {
          throw Error('Source code too large to parse');
        }

        if (__DEBUG__) {
          console.groupCollapsed(
            'loadSourceFiles() fileName "' + fileName + '"',
          );
          console.log(runtimeSourceCode);
          console.groupEnd();
        }

        hookSourceData.runtimeSourceCode = runtimeSourceCode;
      }),
    );
  });
  return Promise.all(promises);
}

async function parseSourceAST(
  fileNameToHookSourceData: Map<string, HookSourceData>,
): Promise<*> {
  // SourceMapConsumer.initialize() does nothing when running in Node (aka Jest)
  // because the wasm file is automatically read from the file system
  // so we can avoid triggering a warning message about this.
  if (!__TEST__) {
    if (__DEBUG__) {
      console.log('parseSourceAST() Initializing source-map library ...');
    }

    // $FlowFixMe
    const wasmMappingsURL = chrome.extension.getURL('mappings.wasm');

    SourceMapConsumer.initialize({'lib/mappings.wasm': wasmMappingsURL});
  }

  const promises = [];
  fileNameToHookSourceData.forEach(hookSourceData => {
    if (hookSourceData.originalSourceAST !== null) {
      // Use cached metadata.
      return;
    }

    const {runtimeSourceCode, sourceMapContents} = hookSourceData;
    if (sourceMapContents !== null) {
      // Parse and extract the AST from the source map.
      promises.push(
        SourceMapConsumer.with(
          sourceMapContents,
          null,
          (sourceConsumer: SourceConsumer) => {
            hookSourceData.sourceConsumer = sourceConsumer;

            // Now that the source map has been loaded,
            // extract the original source for later.
            const source = sourceMapContents.sources[0];
            const originalSourceCode = sourceConsumer.sourceContentFor(
              source,
              true,
            );

            if (__DEBUG__) {
              console.groupCollapsed(
                'parseSourceAST() Extracted source code from source map',
              );
              console.log(originalSourceCode);
              console.groupEnd();
            }

            hookSourceData.originalSourceCode = originalSourceCode;

            // TODO Parsing should ideally be done off of the main thread.
            hookSourceData.originalSourceAST = parse(originalSourceCode, {
              sourceType: 'unambiguous',
              plugins: ['jsx', 'typescript'],
            });
          },
        ),
      );
    } else {
      // There's no source map to parse here so we can just parse the original source itself.
      hookSourceData.originalSourceCode = runtimeSourceCode;

      // TODO Parsing should ideally be done off of the main thread.
      hookSourceData.originalSourceAST = parse(runtimeSourceCode, {
        sourceType: 'unambiguous',
        plugins: ['jsx', 'typescript'],
      });
    }
  });
  return Promise.all(promises);
}

function flattenHooksList(
  hooksTree: HooksTree,
  hooksList: Array<HooksNode>,
): void {
  for (let i = 0; i < hooksTree.length; i++) {
    const hook = hooksTree[i];
    hooksList.push(hook);
    if (hook.subHooks.length > 0) {
      flattenHooksList(hook.subHooks, hooksList);
    }
  }
}

function updateLruCache(
  fileNameToHookSourceData: Map<string, HookSourceData>,
): Promise<*> {
  fileNameToHookSourceData.forEach(
    ({originalSourceAST, originalSourceCode, sourceConsumer}, fileName) => {
      // Only set once to avoid triggering eviction/cleanup code.
      if (!fileNameToMetadataCache.has(fileName)) {
        if (__DEBUG__) {
          console.log('updateLruCache() Caching metada for "' + fileName + '"');
        }

        fileNameToMetadataCache.set(fileName, {
          originalSourceAST,
          originalSourceCode: ((originalSourceCode: any): string),
          sourceConsumer,
        });
      }
    },
  );
  return Promise.resolve();
}