safe-string-coercion.js

/**
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @emails react-core
 */

'use strict';

function isEmptyLiteral(node) {
  return (
    node.type === 'Literal' &&
    typeof node.value === 'string' &&
    node.value === ''
  );
}

function isStringLiteral(node) {
  return (
    // TaggedTemplateExpressions can return non-strings
    (node.type === 'TemplateLiteral' &&
      node.parent.type !== 'TaggedTemplateExpression') ||
    (node.type === 'Literal' && typeof node.value === 'string')
  );
}

// Symbols and Temporal.* objects will throw when using `'' + value`, but that
// pattern can be faster than `String(value)` because JS engines can optimize
// `+` better in some cases. Therefore, in perf-sensitive production codepaths
// we require using `'' + value` for string coercion. The only exception is prod
// error handling code, because it's bad to crash while assembling an error
// message or call stack! Also, error-handling code isn't usually perf-critical.
//
// Non-production codepaths (tests, devtools extension, build tools, etc.)
// should use `String(value)` because it will never crash and the (small) perf
// difference doesn't matter enough for non-prod use cases.
//
// This rule assists enforcing these guidelines:
// * `'' + value` is flagged with a message to remind developers to add a DEV
//   check from shared/CheckStringCoercion.js to make sure that the user gets a
//   clear error message in DEV is the coercion will throw. These checks are not
//   needed if throwing is not possible, e.g. if the value is already known to
//   be a string or number.
// * `String(value)` is flagged only if the `isProductionUserAppCode` option
//   is set. Set this option for prod code files, and don't set it for non-prod
//   files.

const ignoreKeys = [
  'range',
  'raw',
  'parent',
  'loc',
  'start',
  'end',
  '_babelType',
  'leadingComments',
  'trailingComments',
];
function astReplacer(key, value) {
  return ignoreKeys.includes(key) ? undefined : value;
}

/**
 * Simplistic comparison between AST node. Only the following patterns are
 * supported because that's almost all (all?) usage in React:
 * - Identifiers, e.g. `foo`
 * - Member access, e.g. `foo.bar`
 * - Array access with numeric literal, e.g. `foo[0]`
 */
function isEquivalentCode(node1, node2) {
  return (
    JSON.stringify(node1, astReplacer) === JSON.stringify(node2, astReplacer)
  );
}

function isDescendant(node, maybeParentNode) {
  let parent = node.parent;
  while (parent) {
    if (!parent) {
      return false;
    }
    if (parent === maybeParentNode) {
      return true;
    }
    parent = parent.parent;
  }
  return false;
}

function isSafeTypeofExpression(originalValueNode, node) {
  if (node.type === 'BinaryExpression') {
    // Example: typeof foo === 'string'
    if (node.operator !== '===') {
      return false;
    }
    const {left, right} = node;

    // left must be `typeof original`
    if (left.type !== 'UnaryExpression' || left.operator !== 'typeof') {
      return false;
    }
    if (!isEquivalentCode(left.argument, originalValueNode)) {
      return false;
    }
    // right must be a literal value of a safe type
    const safeTypes = ['string', 'number', 'boolean', 'undefined', 'bigint'];
    if (right.type !== 'Literal' || !safeTypes.includes(right.value)) {
      return false;
    }
    return true;
  } else if (node.type === 'LogicalExpression') {
    // Examples:
    // * typeof foo === 'string' && typeof foo === 'number
    // * typeof foo === 'string' && someOtherTest
    if (node.operator === '&&') {
      return (
        isSafeTypeofExpression(originalValueNode, node.left) ||
        isSafeTypeofExpression(originalValueNode, node.right)
      );
    } else if (node.operator === '||') {
      return (
        isSafeTypeofExpression(originalValueNode, node.left) &&
        isSafeTypeofExpression(originalValueNode, node.right)
      );
    }
  }
  return false;
}

/**
  Returns true if the code is inside an `if` block that validates the value
  excludes symbols and objects. Examples:
  * if (typeof value === 'string') { }
  * if (typeof value === 'string' || typeof value === 'number') { }
  * if (typeof value === 'string' || someOtherTest) { }

  @param - originalValueNode Top-level expression to test. Kept unchanged during
  recursion.
  @param - node Expression to test at current recursion level. Will be undefined
  on non-recursive call.
*/
function isInSafeTypeofBlock(originalValueNode, node) {
  if (!node) {
    node = originalValueNode;
  }
  let parent = node.parent;
  while (parent) {
    if (!parent) {
      return false;
    }
    // Normally, if the parent block is inside a type-safe `if` statement,
    // then all child code is also type-safe. But there's a quirky case we
    // need to defend against:
    //   if (typeof obj === 'string') { } else if (typeof obj === 'object') {'' + obj}
    //   if (typeof obj === 'string') { } else {'' + obj}
    // In that code above, the `if` block is safe, but the `else` block is
    // unsafe and should report. But the AST parent of the `else` clause is the
    // `if` statement. This is the one case where the parent doesn't confer
    // safety onto the child. The code below identifies that case and keeps
    // moving up the tree until we get out of the `else`'s parent `if` block.
    // This ensures that we don't use any of these "parents" (really siblings)
    // to confer safety onto the current node.
    if (
      parent.type === 'IfStatement' &&
      !isDescendant(originalValueNode, parent.alternate)
    ) {
      const test = parent.test;
      if (isSafeTypeofExpression(originalValueNode, test)) {
        return true;
      }
    }
    parent = parent.parent;
  }
}

const missingDevCheckMessage =
  'Missing DEV check before this string coercion.' +
  ' Check should be in this format:\n' +
  '  if (__DEV__) {\n' +
  '    checkXxxxxStringCoercion(value);\n' +
  '  }';

const prevStatementNotDevCheckMessage =
  'The statement before this coercion must be a DEV check in this format:\n' +
  '  if (__DEV__) {\n' +
  '    checkXxxxxStringCoercion(value);\n' +
  '  }';

/**
 * Does this node have an "is coercion safe?" DEV check
 * in the same block?
 */
function hasCoercionCheck(node) {
  // find the containing statement
  let topOfExpression = node;
  while (!topOfExpression.parent.body) {
    topOfExpression = topOfExpression.parent;
    if (!topOfExpression) {
      return 'Cannot find top of expression.';
    }
  }
  const containingBlock = topOfExpression.parent.body;
  const index = containingBlock.indexOf(topOfExpression);
  if (index <= 0) {
    return missingDevCheckMessage;
  }
  const prev = containingBlock[index - 1];

  // The previous statement is expected to be like this:
  //   if (__DEV__) {
  //     checkFormFieldValueStringCoercion(foo);
  //   }
  // where `foo` must be equivalent to `node` (which is the
  // mixed value being coerced to a string).
  if (
    prev.type !== 'IfStatement' ||
    prev.test.type !== 'Identifier' ||
    prev.test.name !== '__DEV__'
  ) {
    return prevStatementNotDevCheckMessage;
  }
  let maybeCheckNode = prev.consequent;
  if (maybeCheckNode.type === 'BlockStatement') {
    const body = maybeCheckNode.body;
    if (body.length === 0) {
      return prevStatementNotDevCheckMessage;
    }
    if (body.length !== 1) {
      return (
        'Too many statements in DEV block before this coercion.' +
        ' Expected only one (the check function call). ' +
        prevStatementNotDevCheckMessage
      );
    }
    maybeCheckNode = body[0];
  }

  if (maybeCheckNode.type !== 'ExpressionStatement') {
    return (
      'The DEV block before this coercion must only contain an expression. ' +
      prevStatementNotDevCheckMessage
    );
  }

  const call = maybeCheckNode.expression;
  if (
    call.type !== 'CallExpression' ||
    call.callee.type !== 'Identifier' ||
    !/^check(\w+?)StringCoercion$/.test(call.callee.name) ||
    !call.arguments.length
  ) {
    // `maybeCheckNode` should be a call of a function named checkXXXStringCoercion
    return (
      'Missing or invalid check function call before this coercion.' +
      ' Expected: call of a function like checkXXXStringCoercion. ' +
      prevStatementNotDevCheckMessage
    );
  }

  const same = isEquivalentCode(call.arguments[0], node);
  if (!same) {
    return (
      'Value passed to the check function before this coercion' +
      ' must match the value being coerced.'
    );
  }
}

function isOnlyAddingStrings(node) {
  if (node.operator !== '+') {
    return;
  }
  if (isStringLiteral(node.left) && isStringLiteral(node.right)) {
    // It's always safe to add string literals
    return true;
  }
  if (node.left.type === 'BinaryExpression' && isStringLiteral(node.right)) {
    return isOnlyAddingStrings(node.left);
  }
}

function checkBinaryExpression(context, node) {
  if (isOnlyAddingStrings(node)) {
    return;
  }

  if (
    node.operator === '+' &&
    (isEmptyLiteral(node.left) || isEmptyLiteral(node.right))
  ) {
    let valueToTest = isEmptyLiteral(node.left) ? node.right : node.left;
    if (
      (valueToTest.type === 'TypeCastExpression' ||
        valueToTest.type === 'AsExpression') &&
      valueToTest.expression
    ) {
      valueToTest = valueToTest.expression;
    }

    if (
      valueToTest.type === 'Identifier' &&
      ['i', 'idx', 'lineNumber'].includes(valueToTest.name)
    ) {
      // Common non-object variable names are assumed to be safe
      return;
    }
    if (
      valueToTest.type === 'UnaryExpression' ||
      valueToTest.type === 'UpdateExpression'
    ) {
      // Any unary expression will return a non-object, non-symbol type.
      return;
    }
    if (isInSafeTypeofBlock(valueToTest)) {
      // The value is inside an if (typeof...) block that ensures it's safe
      return;
    }
    const coercionCheckMessage = hasCoercionCheck(valueToTest);
    if (!coercionCheckMessage) {
      // The previous statement is a correct check function call, so no report.
      return;
    }

    context.report({
      node,
      message:
        coercionCheckMessage +
        '\n' +
        "Using `'' + value` or `value + ''` is fast to coerce strings, but may throw." +
        ' For prod code, add a DEV check from shared/CheckStringCoercion immediately' +
        ' before this coercion.' +
        ' For non-prod code and prod error handling, use `String(value)` instead.',
    });
  }
}

function coerceWithStringConstructor(context, node) {
  const isProductionUserAppCode =
    context.options[0] && context.options[0].isProductionUserAppCode;
  if (isProductionUserAppCode && node.callee.name === 'String') {
    context.report(
      node,
      "For perf-sensitive coercion, avoid `String(value)`. Instead, use `'' + value`." +
        ' Precede it with a DEV check from shared/CheckStringCoercion' +
        ' unless Symbol and Temporal.* values are impossible.' +
        ' For non-prod code and prod error handling, use `String(value)` and disable this rule.'
    );
  }
}

module.exports = {
  meta: {
    schema: [
      {
        type: 'object',
        properties: {
          isProductionUserAppCode: {
            type: 'boolean',
            default: false,
          },
        },
        additionalProperties: false,
      },
    ],
  },
  create(context) {
    return {
      BinaryExpression: node => checkBinaryExpression(context, node),
      CallExpression: node => coerceWithStringConstructor(context, node),
    };
  },
};