codtracker-js/node_modules/eslint/lib/rules/no-warning-comments.js

/**
 * @fileoverview Rule that warns about used warning comments
 * @author Alexander Schmidt <https://github.com/lxanders>
 */

'use strict';

const escapeRegExp = require('escape-string-regexp');
const astUtils = require('./utils/ast-utils');

const CHAR_LIMIT = 40;

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

/** @type {import('../types').Rule.RuleModule} */
module.exports = {
  meta: {
    type: 'suggestion',

    defaultOptions: [
      {
        location: 'start',
        terms: ['todo', 'fixme', 'xxx'],
      },
    ],

    docs: {
      description: 'Disallow specified warning terms in comments',
      recommended: false,
      frozen: true,
      url: 'https://eslint.org/docs/latest/rules/no-warning-comments',
    },

    schema: [
      {
        type: 'object',
        properties: {
          terms: {
            type: 'array',
            items: {
              type: 'string',
            },
          },
          location: {
            enum: ['start', 'anywhere'],
          },
          decoration: {
            type: 'array',
            items: {
              type: 'string',
              pattern: '^\\S$',
            },
            minItems: 1,
            uniqueItems: true,
          },
        },
        additionalProperties: false,
      },
    ],

    messages: {
      unexpectedComment: "Unexpected '{{matchedTerm}}' comment: '{{comment}}'.",
    },
  },

  create(context) {
    const sourceCode = context.sourceCode;
    const [{ decoration, location, terms: warningTerms }] = context.options;
    const escapedDecoration = escapeRegExp(
      decoration ? decoration.join('') : ''
    );
    const selfConfigRegEx = /\bno-warning-comments\b/u;

    /**
     * Convert a warning term into a RegExp which will match a comment containing that whole word in the specified
     * location ("start" or "anywhere"). If the term starts or ends with non word characters, then the match will not
     * require word boundaries on that side.
     * @param {string} term A term to convert to a RegExp
     * @returns {RegExp} The term converted to a RegExp
     */
    function convertToRegExp(term) {
      const escaped = escapeRegExp(term);

      /*
       * When matching at the start, ignore leading whitespace, and
       * there's no need to worry about word boundaries.
       *
       * These expressions for the prefix and suffix are designed as follows:
       * ^   handles any terms at the beginning of a comment.
       *     e.g. terms ["TODO"] matches `//TODO something`
       * $   handles any terms at the end of a comment
       *     e.g. terms ["TODO"] matches `// something TODO`
       * \b  handles terms preceded/followed by word boundary
       *     e.g. terms: ["!FIX", "FIX!"] matches `// FIX!something` or `// something!FIX`
       *          terms: ["FIX"] matches `// FIX!` or `// !FIX`, but not `// fixed or affix`
       *
       * For location start:
       * [\s]* handles optional leading spaces
       *     e.g. terms ["TODO"] matches `//    TODO something`
       * [\s\*]* (where "\*" is the escaped string of decoration)
       *     handles optional leading spaces or decoration characters (for "start" location only)
       *     e.g. terms ["TODO"] matches `/**** TODO something ... `
       */
      const wordBoundary = '\\b';

      let prefix = '';

      if (location === 'start') {
        prefix = `^[\\s${escapedDecoration}]*`;
      } else if (/^\w/u.test(term)) {
        prefix = wordBoundary;
      }

      const suffix = /\w$/u.test(term) ? wordBoundary : '';
      const flags = 'iu'; // Case-insensitive with Unicode case folding.

      /*
       * For location "start", the typical regex is:
       *   /^[\s]*ESCAPED_TERM\b/iu.
       * Or if decoration characters are specified (e.g. "*"), then any of
       * those characters may appear in any order at the start:
       *   /^[\s\*]*ESCAPED_TERM\b/iu.
       *
       * For location "anywhere" the typical regex is
       *   /\bESCAPED_TERM\b/iu
       *
       * If it starts or ends with non-word character, the prefix and suffix are empty, respectively.
       */
      return new RegExp(`${prefix}${escaped}${suffix}`, flags);
    }

    const warningRegExps = warningTerms.map(convertToRegExp);

    /**
     * Checks the specified comment for matches of the configured warning terms and returns the matches.
     * @param {string} comment The comment which is checked.
     * @returns {Array} All matched warning terms for this comment.
     */
    function commentContainsWarningTerm(comment) {
      const matches = [];

      warningRegExps.forEach((regex, index) => {
        if (regex.test(comment)) {
          matches.push(warningTerms[index]);
        }
      });

      return matches;
    }

    /**
     * Checks the specified node for matching warning comments and reports them.
     * @param {ASTNode} node The AST node being checked.
     * @returns {void} undefined.
     */
    function checkComment(node) {
      const comment = node.value;

      if (astUtils.isDirectiveComment(node) && selfConfigRegEx.test(comment)) {
        return;
      }

      const matches = commentContainsWarningTerm(comment);

      matches.forEach((matchedTerm) => {
        let commentToDisplay = '';
        let truncated = false;

        for (const c of comment.trim().split(/\s+/u)) {
          const tmp = commentToDisplay ? `${commentToDisplay} ${c}` : c;

          if (tmp.length <= CHAR_LIMIT) {
            commentToDisplay = tmp;
          } else {
            truncated = true;
            break;
          }
        }

        context.report({
          node,
          messageId: 'unexpectedComment',
          data: {
            matchedTerm,
            comment: `${commentToDisplay}${truncated ? '...' : ''}`,
          },
        });
      });
    }

    return {
      Program() {
        const comments = sourceCode.getAllComments();

        comments
          .filter((token) => token.type !== 'Shebang')
          .forEach(checkComment);
      },
    };
  },
};