/**
 * @fileoverview Rule to flag constant comparisons and logical expressions that always/never short circuit
 * @author Jordan Eldredge <https://jordaneldredge.com>
 */

'use strict';

const {
  isNullLiteral,
  isConstant,
  isReferenceToGlobalVariable,
  isLogicalAssignmentOperator,
  ECMASCRIPT_GLOBALS,
} = require('./utils/ast-utils');

const NUMERIC_OR_STRING_BINARY_OPERATORS = new Set([
  '+',
  '-',
  '*',
  '/',
  '%',
  '|',
  '^',
  '&',
  '**',
  '<<',
  '>>',
  '>>>',
]);

//------------------------------------------------------------------------------
// Helpers
//------------------------------------------------------------------------------

/**
 * Checks whether or not a node is `null` or `undefined`. Similar to the one
 * found in ast-utils.js, but this one correctly handles the edge case that
 * `undefined` has been redefined.
 * @param {Scope} scope Scope in which the expression was found.
 * @param {ASTNode} node A node to check.
 * @returns {boolean} Whether or not the node is a `null` or `undefined`.
 * @public
 */
function isNullOrUndefined(scope, node) {
  return (
    isNullLiteral(node) ||
    (node.type === 'Identifier' &&
      node.name === 'undefined' &&
      isReferenceToGlobalVariable(scope, node)) ||
    (node.type === 'UnaryExpression' && node.operator === 'void')
  );
}

/**
 * Test if an AST node has a statically knowable constant nullishness. Meaning,
 * it will always resolve to a constant value of either: `null`, `undefined`
 * or not `null` _or_ `undefined`. An expression that can vary between those
 * three states at runtime would return `false`.
 * @param {Scope} scope The scope in which the node was found.
 * @param {ASTNode} node The AST node being tested.
 * @param {boolean} nonNullish if `true` then nullish values are not considered constant.
 * @returns {boolean} Does `node` have constant nullishness?
 */
function hasConstantNullishness(scope, node, nonNullish) {
  if (nonNullish && isNullOrUndefined(scope, node)) {
    return false;
  }

  switch (node.type) {
    case 'ObjectExpression': // Objects are never nullish
    case 'ArrayExpression': // Arrays are never nullish
    case 'ArrowFunctionExpression': // Functions never nullish
    case 'FunctionExpression': // Functions are never nullish
    case 'ClassExpression': // Classes are never nullish
    case 'NewExpression': // Objects are never nullish
    case 'Literal': // Nullish, or non-nullish, literals never change
    case 'TemplateLiteral': // A string is never nullish
    case 'UpdateExpression': // Numbers are never nullish
    case 'BinaryExpression': // Numbers, strings, or booleans are never nullish
      return true;
    case 'CallExpression': {
      if (node.callee.type !== 'Identifier') {
        return false;
      }
      const functionName = node.callee.name;

      return (
        (functionName === 'Boolean' ||
          functionName === 'String' ||
          functionName === 'Number') &&
        isReferenceToGlobalVariable(scope, node.callee)
      );
    }
    case 'LogicalExpression': {
      return (
        node.operator === '??' &&
        hasConstantNullishness(scope, node.right, true)
      );
    }
    case 'AssignmentExpression':
      if (node.operator === '=') {
        return hasConstantNullishness(scope, node.right, nonNullish);
      }

      /*
       * Handling short-circuiting assignment operators would require
       * walking the scope. We won't attempt that (for now...) /
       */
      if (isLogicalAssignmentOperator(node.operator)) {
        return false;
      }

      /*
       * The remaining assignment expressions all result in a numeric or
       * string (non-nullish) value:
       *   "+=", "-=", "*=", "/=", "%=", "<<=", ">>=", ">>>=", "|=", "^=", "&="
       */

      return true;
    case 'UnaryExpression':
      /*
       * "void" Always returns `undefined`
       * "typeof" All types are strings, and thus non-nullish
       * "!" Boolean is never nullish
       * "delete" Returns a boolean, which is never nullish
       * Math operators always return numbers or strings, neither of which
       * are non-nullish "+", "-", "~"
       */

      return true;
    case 'SequenceExpression': {
      const last = node.expressions.at(-1);

      return hasConstantNullishness(scope, last, nonNullish);
    }
    case 'Identifier':
      return (
        node.name === 'undefined' && isReferenceToGlobalVariable(scope, node)
      );
    case 'JSXElement': // ESLint has a policy of not assuming any specific JSX behavior.
    case 'JSXFragment':
      return false;
    default:
      return false;
  }
}

/**
 * Test if an AST node is a boolean value that never changes. Specifically we
 * test for:
 * 1. Literal booleans (`true` or `false`)
 * 2. Unary `!` expressions with a constant value
 * 3. Constant booleans created via the `Boolean` global function
 * @param {Scope} scope The scope in which the node was found.
 * @param {ASTNode} node The node to test
 * @returns {boolean} Is `node` guaranteed to be a boolean?
 */
function isStaticBoolean(scope, node) {
  switch (node.type) {
    case 'Literal':
      return typeof node.value === 'boolean';
    case 'CallExpression':
      return (
        node.callee.type === 'Identifier' &&
        node.callee.name === 'Boolean' &&
        isReferenceToGlobalVariable(scope, node.callee) &&
        (node.arguments.length === 0 ||
          isConstant(scope, node.arguments[0], true))
      );
    case 'UnaryExpression':
      return node.operator === '!' && isConstant(scope, node.argument, true);
    default:
      return false;
  }
}

/**
 * Test if an AST node will always give the same result when compared to a
 * boolean value. Note that comparison to boolean values is different than
 * truthiness.
 * https://262.ecma-international.org/5.1/#sec-11.9.3
 *
 * JavaScript `==` operator works by converting the boolean to `1` (true) or
 * `+0` (false) and then checks the values `==` equality to that number.
 * @param {Scope} scope The scope in which node was found.
 * @param {ASTNode} node The node to test.
 * @returns {boolean} Will `node` always coerce to the same boolean value?
 */
function hasConstantLooseBooleanComparison(scope, node) {
  switch (node.type) {
    case 'ObjectExpression':
    case 'ClassExpression':
      /**
       * In theory objects like:
       *
       * `{toString: () => a}`
       * `{valueOf: () => a}`
       *
       * Or a classes like:
       *
       * `class { static toString() { return a } }`
       * `class { static valueOf() { return a } }`
       *
       * Are not constant verifiably when `inBooleanPosition` is
       * false, but it's an edge case we've opted not to handle.
       */
      return true;
    case 'ArrayExpression': {
      const nonSpreadElements = node.elements.filter(
        (e) =>
          // Elements can be `null` in sparse arrays: `[,,]`;
          e !== null && e.type !== 'SpreadElement'
      );

      /*
       * Possible future direction if needed: We could check if the
       * single value would result in variable boolean comparison.
       * For now we will err on the side of caution since `[x]` could
       * evaluate to `[0]` or `[1]`.
       */
      return node.elements.length === 0 || nonSpreadElements.length > 1;
    }
    case 'ArrowFunctionExpression':
    case 'FunctionExpression':
      return true;
    case 'UnaryExpression':
      if (
        node.operator === 'void' || // Always returns `undefined`
        node.operator === 'typeof' // All `typeof` strings, when coerced to number, are not 0 or 1.
      ) {
        return true;
      }
      if (node.operator === '!') {
        return isConstant(scope, node.argument, true);
      }

      /*
       * We won't try to reason about +, -, ~, or delete
       * In theory, for the mathematical operators, we could look at the
       * argument and try to determine if it coerces to a constant numeric
       * value.
       */
      return false;
    case 'NewExpression': // Objects might have custom `.valueOf` or `.toString`.
      return false;
    case 'CallExpression': {
      if (
        node.callee.type === 'Identifier' &&
        node.callee.name === 'Boolean' &&
        isReferenceToGlobalVariable(scope, node.callee)
      ) {
        return (
          node.arguments.length === 0 ||
          isConstant(scope, node.arguments[0], true)
        );
      }
      return false;
    }
    case 'Literal': // True or false, literals never change
      return true;
    case 'Identifier':
      return (
        node.name === 'undefined' && isReferenceToGlobalVariable(scope, node)
      );
    case 'TemplateLiteral':
      /*
       * In theory we could try to check if the quasi are sufficient to
       * prove that the expression will always be true, but it would be
       * tricky to get right. For example: `000.${foo}000`
       */
      return node.expressions.length === 0;
    case 'AssignmentExpression':
      if (node.operator === '=') {
        return hasConstantLooseBooleanComparison(scope, node.right);
      }

      /*
       * Handling short-circuiting assignment operators would require
       * walking the scope. We won't attempt that (for now...)
       *
       * The remaining assignment expressions all result in a numeric or
       * string (non-nullish) values which could be truthy or falsy:
       *   "+=", "-=", "*=", "/=", "%=", "<<=", ">>=", ">>>=", "|=", "^=", "&="
       */
      return false;
    case 'SequenceExpression': {
      const last = node.expressions.at(-1);

      return hasConstantLooseBooleanComparison(scope, last);
    }
    case 'JSXElement': // ESLint has a policy of not assuming any specific JSX behavior.
    case 'JSXFragment':
      return false;
    default:
      return false;
  }
}

/**
 * Test if an AST node will always give the same result when _strictly_ compared
 * to a boolean value. This can happen if the expression can never be boolean, or
 * if it is always the same boolean value.
 * @param {Scope} scope The scope in which the node was found.
 * @param {ASTNode} node The node to test
 * @returns {boolean} Will `node` always give the same result when compared to a
 * static boolean value?
 */
function hasConstantStrictBooleanComparison(scope, node) {
  switch (node.type) {
    case 'ObjectExpression': // Objects are not booleans
    case 'ArrayExpression': // Arrays are not booleans
    case 'ArrowFunctionExpression': // Functions are not booleans
    case 'FunctionExpression':
    case 'ClassExpression': // Classes are not booleans
    case 'NewExpression': // Objects are not booleans
    case 'TemplateLiteral': // Strings are not booleans
    case 'Literal': // True, false, or not boolean, literals never change.
    case 'UpdateExpression': // Numbers are not booleans
      return true;
    case 'BinaryExpression':
      return NUMERIC_OR_STRING_BINARY_OPERATORS.has(node.operator);
    case 'UnaryExpression': {
      if (node.operator === 'delete') {
        return false;
      }
      if (node.operator === '!') {
        return isConstant(scope, node.argument, true);
      }

      /*
       * The remaining operators return either strings or numbers, neither
       * of which are boolean.
       */
      return true;
    }
    case 'SequenceExpression': {
      const last = node.expressions.at(-1);

      return hasConstantStrictBooleanComparison(scope, last);
    }
    case 'Identifier':
      return (
        node.name === 'undefined' && isReferenceToGlobalVariable(scope, node)
      );
    case 'AssignmentExpression':
      if (node.operator === '=') {
        return hasConstantStrictBooleanComparison(scope, node.right);
      }

      /*
       * Handling short-circuiting assignment operators would require
       * walking the scope. We won't attempt that (for now...)
       */
      if (isLogicalAssignmentOperator(node.operator)) {
        return false;
      }

      /*
       * The remaining assignment expressions all result in either a number
       * or a string, neither of which can ever be boolean.
       */
      return true;
    case 'CallExpression': {
      if (node.callee.type !== 'Identifier') {
        return false;
      }
      const functionName = node.callee.name;

      if (
        (functionName === 'String' || functionName === 'Number') &&
        isReferenceToGlobalVariable(scope, node.callee)
      ) {
        return true;
      }
      if (
        functionName === 'Boolean' &&
        isReferenceToGlobalVariable(scope, node.callee)
      ) {
        return (
          node.arguments.length === 0 ||
          isConstant(scope, node.arguments[0], true)
        );
      }
      return false;
    }
    case 'JSXElement': // ESLint has a policy of not assuming any specific JSX behavior.
    case 'JSXFragment':
      return false;
    default:
      return false;
  }
}

/**
 * Test if an AST node will always result in a newly constructed object
 * @param {Scope} scope The scope in which the node was found.
 * @param {ASTNode} node The node to test
 * @returns {boolean} Will `node` always be new?
 */
function isAlwaysNew(scope, node) {
  switch (node.type) {
    case 'ObjectExpression':
    case 'ArrayExpression':
    case 'ArrowFunctionExpression':
    case 'FunctionExpression':
    case 'ClassExpression':
      return true;
    case 'NewExpression': {
      if (node.callee.type !== 'Identifier') {
        return false;
      }

      /*
       * All the built-in constructors are always new, but
       * user-defined constructors could return a sentinel
       * object.
       *
       * Catching these is especially useful for primitive constructors
       * which return boxed values, a surprising gotcha' in JavaScript.
       */
      return (
        Object.hasOwn(ECMASCRIPT_GLOBALS, node.callee.name) &&
        isReferenceToGlobalVariable(scope, node.callee)
      );
    }
    case 'Literal':
      // Regular expressions are objects, and thus always new
      return typeof node.regex === 'object';
    case 'SequenceExpression': {
      const last = node.expressions.at(-1);

      return isAlwaysNew(scope, last);
    }
    case 'AssignmentExpression':
      if (node.operator === '=') {
        return isAlwaysNew(scope, node.right);
      }
      return false;
    case 'ConditionalExpression':
      return (
        isAlwaysNew(scope, node.consequent) &&
        isAlwaysNew(scope, node.alternate)
      );
    case 'JSXElement': // ESLint has a policy of not assuming any specific JSX behavior.
    case 'JSXFragment':
      return false;
    default:
      return false;
  }
}

/**
 * Checks if one operand will cause the result to be constant.
 * @param {Scope} scope Scope in which the expression was found.
 * @param {ASTNode} a One side of the expression
 * @param {ASTNode} b The other side of the expression
 * @param {string} operator The binary expression operator
 * @returns {ASTNode | null} The node which will cause the expression to have a constant result.
 */
function findBinaryExpressionConstantOperand(scope, a, b, operator) {
  if (operator === '==' || operator === '!=') {
    if (
      (isNullOrUndefined(scope, a) &&
        hasConstantNullishness(scope, b, false)) ||
      (isStaticBoolean(scope, a) && hasConstantLooseBooleanComparison(scope, b))
    ) {
      return b;
    }
  } else if (operator === '===' || operator === '!==') {
    if (
      (isNullOrUndefined(scope, a) &&
        hasConstantNullishness(scope, b, false)) ||
      (isStaticBoolean(scope, a) &&
        hasConstantStrictBooleanComparison(scope, b))
    ) {
      return b;
    }
  }
  return null;
}

//------------------------------------------------------------------------------
// Rule Definition
//------------------------------------------------------------------------------

/** @type {import('../types').Rule.RuleModule} */
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description:
        "Disallow expressions where the operation doesn't affect the value",
      recommended: true,
      url: 'https://eslint.org/docs/latest/rules/no-constant-binary-expression',
    },
    schema: [],
    messages: {
      constantBinaryOperand:
        'Unexpected constant binary expression. Compares constantly with the {{otherSide}}-hand side of the `{{operator}}`.',
      constantShortCircuit:
        'Unexpected constant {{property}} on the left-hand side of a `{{operator}}` expression.',
      alwaysNew:
        'Unexpected comparison to newly constructed object. These two values can never be equal.',
      bothAlwaysNew:
        'Unexpected comparison of two newly constructed objects. These two values can never be equal.',
    },
  },

  create(context) {
    const sourceCode = context.sourceCode;

    return {
      LogicalExpression(node) {
        const { operator, left } = node;
        const scope = sourceCode.getScope(node);

        if (
          (operator === '&&' || operator === '||') &&
          isConstant(scope, left, true)
        ) {
          context.report({
            node: left,
            messageId: 'constantShortCircuit',
            data: { property: 'truthiness', operator },
          });
        } else if (
          operator === '??' &&
          hasConstantNullishness(scope, left, false)
        ) {
          context.report({
            node: left,
            messageId: 'constantShortCircuit',
            data: { property: 'nullishness', operator },
          });
        }
      },
      BinaryExpression(node) {
        const scope = sourceCode.getScope(node);
        const { right, left, operator } = node;
        const rightConstantOperand = findBinaryExpressionConstantOperand(
          scope,
          left,
          right,
          operator
        );
        const leftConstantOperand = findBinaryExpressionConstantOperand(
          scope,
          right,
          left,
          operator
        );

        if (rightConstantOperand) {
          context.report({
            node: rightConstantOperand,
            messageId: 'constantBinaryOperand',
            data: { operator, otherSide: 'left' },
          });
        } else if (leftConstantOperand) {
          context.report({
            node: leftConstantOperand,
            messageId: 'constantBinaryOperand',
            data: { operator, otherSide: 'right' },
          });
        } else if (operator === '===' || operator === '!==') {
          if (isAlwaysNew(scope, left)) {
            context.report({ node: left, messageId: 'alwaysNew' });
          } else if (isAlwaysNew(scope, right)) {
            context.report({ node: right, messageId: 'alwaysNew' });
          }
        } else if (operator === '==' || operator === '!=') {
          /*
           * If both sides are "new", then both sides are objects and
           * therefore they will be compared by reference even with `==`
           * equality.
           */
          if (isAlwaysNew(scope, left) && isAlwaysNew(scope, right)) {
            context.report({
              node: left,
              messageId: 'bothAlwaysNew',
            });
          }
        }
      },

      /*
       * In theory we could handle short-circuiting assignment operators,
       * for some constant values, but that would require walking the
       * scope to find the value of the variable being assigned. This is
       * dependent on https://github.com/eslint/eslint/issues/13776
       *
       * AssignmentExpression() {},
       */
    };
  },
};