enable eslint-comments/require-description

.eslintrc.js

@@ -420,6 +420,9 @@ const base = {
   'radar/prefer-single-boolean-return': 'error',
   // a `while` loop should be used instead of a `for` loop with condition only
   'radar/prefer-while': 'error',
+
+  // eslint-comments
+  'eslint-comments/require-description': 'error',
 };
 
 const es3 = {
@@ -559,6 +562,7 @@ module.exports = {
     worker: true,
   },
   plugins: [
+    'eslint-comments',
     'import',
     'node',
     'optimize-regex',

Gruntfile.js

@@ -1,4 +1,4 @@
-/* eslint-disable unicorn/filename-case */
+/* eslint-disable unicorn/filename-case -- 3rd-party tool */
 'use strict';
 const webpack = require('./.webpack.config.js');
 const { banner } = require('./packages/core-js-builder/config');
@@ -164,8 +164,7 @@ module.exports = grunt => {
     webpack,
   });
   grunt.registerTask('bundle', function () {
-    // some dependencies of this module generated in grunt tasks, so we should load it here
-    // eslint-disable-next-line node/global-require
+    // eslint-disable-next-line node/global-require -- some dependencies of this module generated in grunt tasks
     const builder = require('./packages/core-js-builder');
     const done = this.async();
 

package.json

@@ -29,6 +29,7 @@
     "es-observable": "git+https://github.com/tc39/proposal-observable.git#d3404f06bc70c7c578a5047dfb3dc813730e3319",
     "eslint": "^7.19.0",
     "eslint-import-resolver-webpack": "~0.13.0",
+    "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-import": "^2.22.1",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-optimize-regex": "^1.2.0",

packages/core-js-builder/config.js

@@ -2,12 +2,12 @@
 const { version } = require('./package');
 
 module.exports = {
-  /* eslint-disable prefer-template */
+  /* eslint-disable prefer-template -- for better formatting */
   banner: '/**\n' +
           ' * core-js ' + version + '\n' +
           ' * https://github.com/zloirock/core-js\n' +
           ' * License: http://rock.mit-license.org\n' +
           ' * © ' + new Date().getFullYear() + ' Denis Pushkarev (zloirock.ru)\n' +
           ' */',
-  /* eslint-enable prefer-template */
+  /* eslint-enable prefer-template -- for better formatting */
 };

packages/core-js-compat/src/build-data.js

@@ -75,5 +75,5 @@ writeJSON('../data.json', data);
 writeJSON('../modules.json', Object.keys(data));
 writeJSON('../external.json', external);
 
-// eslint-disable-next-line no-console
+// eslint-disable-next-line no-console -- output
 console.log('\u001B[32mcompat data rebuilt\u001B[0m');

packages/core-js-compat/src/build-entries.js

@@ -39,5 +39,5 @@ const entries = [
 
 writeFileSync(resolve(__dirname, '../entries.json'), JSON.stringify(sortObjectByKey(entries), null, '  '));
 
-// eslint-disable-next-line no-console
+// eslint-disable-next-line no-console -- output
 console.log('\u001B[32mentries data rebuilt\u001B[0m');

packages/core-js-compat/src/build-modules-by-versions.js

@@ -15,5 +15,5 @@ writeFileSync(resolve(__dirname, '../modules-by-versions.json'), JSON.stringify(
   ...modulesByVersions,
 }, null, '  '));
 
-// eslint-disable-next-line no-console
+// eslint-disable-next-line no-console -- output
 console.log('\u001B[32mmodules-by-versions data rebuilt\u001B[0m');

packages/core-js-pure/override/modules/es.date.to-json.js

@@ -14,7 +14,7 @@ var FORCED = fails(function () {
 // `Date.prototype.toJSON` method
 // https://tc39.es/ecma262/#sec-date.prototype.tojson
 $({ target: 'Date', proto: true, forced: FORCED }, {
-  // eslint-disable-next-line no-unused-vars
+  // eslint-disable-next-line no-unused-vars -- required for `.length`
   toJSON: function toJSON(key) {
     var O = toObject(this);
     var pv = toPrimitive(O);

packages/core-js/es/json/stringify.js

@@ -3,7 +3,7 @@ var core = require('../../internals/path');
 
 if (!core.JSON) core.JSON = { stringify: JSON.stringify };
 
-// eslint-disable-next-line no-unused-vars
+// eslint-disable-next-line no-unused-vars -- required for `.length`
 module.exports = function stringify(it, replacer, space) {
   return core.JSON.stringify.apply(null, arguments);
 };

packages/core-js/internals/array-buffer-view-core.js

@@ -122,7 +122,7 @@ for (NAME in TypedArrayConstructorsList) {
 
 // WebKit bug - typed arrays constructors prototype is Object.prototype
 if (!NATIVE_ARRAY_BUFFER_VIEWS || typeof TypedArray != 'function' || TypedArray === Function.prototype) {
-  // eslint-disable-next-line no-shadow
+  // eslint-disable-next-line no-shadow -- safe
   TypedArray = function TypedArray() {
     throw TypeError('Incorrect invocation');
   };

packages/core-js/internals/array-buffer.js

@@ -174,16 +174,18 @@ if (!NATIVE_ARRAY_BUFFER) {
     }
   });
 } else {
+  /* eslint-disable no-new -- required for testing */
   if (!fails(function () {
     NativeArrayBuffer(1);
   }) || !fails(function () {
-    new NativeArrayBuffer(-1); // eslint-disable-line no-new
+    new NativeArrayBuffer(-1);
   }) || fails(function () {
-    new NativeArrayBuffer(); // eslint-disable-line no-new
-    new NativeArrayBuffer(1.5); // eslint-disable-line no-new
-    new NativeArrayBuffer(NaN); // eslint-disable-line no-new
+    new NativeArrayBuffer();
+    new NativeArrayBuffer(1.5);
+    new NativeArrayBuffer(NaN);
     return NativeArrayBuffer.name != ARRAY_BUFFER;
   })) {
+  /* eslint-enable no-new -- required for testing */
     $ArrayBuffer = function ArrayBuffer(length) {
       anInstance(this, $ArrayBuffer);
       return new NativeArrayBuffer(toIndex(length));

packages/core-js/internals/array-includes.js

@@ -10,10 +10,10 @@ var createMethod = function (IS_INCLUDES) {
     var index = toAbsoluteIndex(fromIndex, length);
     var value;
     // Array#includes uses SameValueZero equality algorithm
-    // eslint-disable-next-line no-self-compare
+    // eslint-disable-next-line no-self-compare -- NaN check
     if (IS_INCLUDES && el != el) while (length > index) {
       value = O[index++];
-      // eslint-disable-next-line no-self-compare
+      // eslint-disable-next-line no-self-compare -- NaN check
       if (value != value) return true;
     // Array#indexOf ignores holes, Array#includes - not
     } else for (;length > index; index++) {

packages/core-js/internals/array-method-is-strict.js

@@ -4,7 +4,7 @@ var fails = require('../internals/fails');
 module.exports = function (METHOD_NAME, argument) {
   var method = [][METHOD_NAME];
   return !!method && fails(function () {
-    // eslint-disable-next-line no-useless-call,no-throw-literal
+    // eslint-disable-next-line no-useless-call,no-throw-literal -- required for testing
     method.call(null, argument || function () { throw 1; }, 1);
   });
 };

packages/core-js/internals/async-iterator-prototype.js

@@ -19,7 +19,7 @@ if (!IS_PURE) {
     AsyncIteratorPrototype = AsyncIterator.prototype;
   } else if (shared[USE_FUNCTION_CONSTRUCTOR] || global[USE_FUNCTION_CONSTRUCTOR]) {
     try {
-      // eslint-disable-next-line no-new-func
+      // eslint-disable-next-line no-new-func -- we have no alternatives without usage of modern syntax
       prototype = getPrototypeOf(getPrototypeOf(getPrototypeOf(Function('return async function*(){}()')())));
       if (getPrototypeOf(prototype) === Object.prototype) AsyncIteratorPrototype = prototype;
     } catch (error) { /* empty */ }

packages/core-js/internals/check-correctness-of-iteration.js

@@ -16,7 +16,7 @@ try {
   iteratorWithReturn[ITERATOR] = function () {
     return this;
   };
-  // eslint-disable-next-line no-throw-literal
+  // eslint-disable-next-line no-throw-literal -- required for testing
   Array.from(iteratorWithReturn, function () { throw 2; });
 } catch (error) { /* empty */ }
 

packages/core-js/internals/collection.js

@@ -40,10 +40,14 @@ module.exports = function (CONSTRUCTOR_NAME, wrapper, common) {
     );
   };
 
-  // eslint-disable-next-line max-len
-  if (isForced(CONSTRUCTOR_NAME, typeof NativeConstructor != 'function' || !(IS_WEAK || NativePrototype.forEach && !fails(function () {
-    new NativeConstructor().entries().next();
-  })))) {
+  var REPLACE = isForced(
+    CONSTRUCTOR_NAME,
+    typeof NativeConstructor != 'function' || !(IS_WEAK || NativePrototype.forEach && !fails(function () {
+      new NativeConstructor().entries().next();
+    }))
+  );
+
+  if (REPLACE) {
     // create collection constructor
     Constructor = common.getConstructor(wrapper, CONSTRUCTOR_NAME, IS_MAP, ADDER);
     InternalMetadataModule.REQUIRED = true;
@@ -54,7 +58,7 @@ module.exports = function (CONSTRUCTOR_NAME, wrapper, common) {
     // V8 ~ Chromium 40- weak-collections throws on primitives, but should return false
     var THROWS_ON_PRIMITIVES = fails(function () { instance.has(1); });
     // most early implementations doesn't supports iterables, most modern - not close it correctly
-    // eslint-disable-next-line no-new
+    // eslint-disable-next-line no-new -- required for testing
     var ACCEPT_ITERABLES = checkCorrectnessOfIteration(function (iterable) { new NativeConstructor(iterable); });
     // for early implementations -0 and +0 not the same
     var BUGGY_ZERO = !IS_WEAK && fails(function () {

packages/core-js/internals/function-bind.js

@@ -8,7 +8,7 @@ var factories = {};
 var construct = function (C, argsLength, args) {
   if (!(argsLength in factories)) {
     for (var list = [], i = 0; i < argsLength; i++) list[i] = 'a[' + i + ']';
-    // eslint-disable-next-line no-new-func
+    // eslint-disable-next-line no-new-func -- we have no proper alternatives, IE8- only
     factories[argsLength] = Function('C,a', 'return new C(' + list.join(',') + ')');
   } return factories[argsLength](C, args);
 };

packages/core-js/internals/get-map-iterator.js

@@ -2,6 +2,6 @@ var IS_PURE = require('../internals/is-pure');
 var getIterator = require('../internals/get-iterator');
 
 module.exports = IS_PURE ? getIterator : function (it) {
-  // eslint-disable-next-line no-undef
+  // eslint-disable-next-line no-undef -- safe
   return Map.prototype.entries.call(it);
 };

packages/core-js/internals/get-set-iterator.js

@@ -2,6 +2,6 @@ var IS_PURE = require('../internals/is-pure');
 var getIterator = require('../internals/get-iterator');
 
 module.exports = IS_PURE ? getIterator : function (it) {
-  // eslint-disable-next-line no-undef
+  // eslint-disable-next-line no-undef -- safe
   return Set.prototype.values.call(it);
 };

packages/core-js/internals/global.js

@@ -4,10 +4,10 @@ var check = function (it) {
 
 // https://github.com/zloirock/core-js/issues/86#issuecomment-115759028
 module.exports =
-  // eslint-disable-next-line no-undef
+  /* global globalThis -- safe */
   check(typeof globalThis == 'object' && globalThis) ||
   check(typeof window == 'object' && window) ||
   check(typeof self == 'object' && self) ||
   check(typeof global == 'object' && global) ||
-  // eslint-disable-next-line no-new-func
+  // eslint-disable-next-line no-new-func -- fallback
   (function () { return this; })() || Function('return this')();

packages/core-js/internals/ieee754.js

@@ -1,5 +1,5 @@
 // IEEE754 conversions based on https://github.com/feross/ieee754
-// eslint-disable-next-line no-shadow-restricted-names
+// eslint-disable-next-line no-shadow-restricted-names -- for better compression
 var Infinity = 1 / 0;
 var abs = Math.abs;
 var pow = Math.pow;
@@ -17,9 +17,9 @@ var pack = function (number, mantissaLength, bytes) {
   var index = 0;
   var exponent, mantissa, c;
   number = abs(number);
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   if (number != number || number === Infinity) {
-    // eslint-disable-next-line no-self-compare
+    // eslint-disable-next-line no-self-compare -- NaN check
     mantissa = number != number ? 1 : 0;
     exponent = eMax;
   } else {

packages/core-js/internals/indexed-object.js

@@ -6,7 +6,7 @@ var split = ''.split;
 // fallback for non-array-like ES3 and non-enumerable old V8 strings
 module.exports = fails(function () {
   // throws an error in rhino, see https://github.com/mozilla/rhino/issues/346
-  // eslint-disable-next-line no-prototype-builtins
+  // eslint-disable-next-line no-prototype-builtins -- safe
   return !Object('z').propertyIsEnumerable(0);
 }) ? function (it) {
   return classof(it) == 'String' ? split.call(it, '') : Object(it);

packages/core-js/internals/is-iterable.js

@@ -8,6 +8,6 @@ module.exports = function (it) {
   var O = Object(it);
   return O[ITERATOR] !== undefined
     || '@@iterator' in O
-    // eslint-disable-next-line no-prototype-builtins
+    // eslint-disable-next-line no-prototype-builtins -- safe
     || Iterators.hasOwnProperty(classof(O));
 };

packages/core-js/internals/math-fround.js

@@ -20,7 +20,7 @@ module.exports = Math.fround || function fround(x) {
   if ($abs < MIN32) return $sign * roundTiesToEven($abs / MIN32 / EPSILON32) * MIN32 * EPSILON32;
   a = (1 + EPSILON32 / EPSILON) * $abs;
   result = a - (a - $abs);
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   if (result > MAX32 || result != result) return $sign * Infinity;
   return $sign * result;
 };

packages/core-js/internals/math-scale.js

@@ -3,13 +3,13 @@
 module.exports = Math.scale || function scale(x, inLow, inHigh, outLow, outHigh) {
   if (
     arguments.length === 0
-      /* eslint-disable no-self-compare */
+      /* eslint-disable no-self-compare -- NaN check */
       || x != x
       || inLow != inLow
       || inHigh != inHigh
       || outLow != outLow
       || outHigh != outHigh
-      /* eslint-enable no-self-compare */
+      /* eslint-enable no-self-compare -- NaN check */
   ) return NaN;
   if (x === Infinity || x === -Infinity) return x;
   return (x - inLow) * (outHigh - outLow) / (inHigh - inLow) + outLow;

packages/core-js/internals/math-sign.js

@@ -1,6 +1,6 @@
 // `Math.sign` method implementation
 // https://tc39.es/ecma262/#sec-math.sign
 module.exports = Math.sign || function sign(x) {
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   return (x = +x) == 0 || x != x ? x : x < 0 ? -1 : 1;
 };

packages/core-js/internals/native-symbol.js

@@ -2,6 +2,6 @@ var fails = require('../internals/fails');
 
 module.exports = !!Object.getOwnPropertySymbols && !fails(function () {
   // Chrome 38 Symbol has incorrect toString conversion
-  // eslint-disable-next-line no-undef
+  /* global Symbol -- required for testing */
   return !String(Symbol());
 });

packages/core-js/internals/object-assign.js

@@ -26,13 +26,13 @@ module.exports = !nativeAssign || fails(function () {
   // should work with symbols and should have deterministic property order (V8 bug)
   var A = {};
   var B = {};
-  // eslint-disable-next-line no-undef
+  /* global Symbol -- required for testing */
   var symbol = Symbol();
   var alphabet = 'abcdefghijklmnopqrst';
   A[symbol] = 7;
   alphabet.split('').forEach(function (chr) { B[chr] = chr; });
   return nativeAssign({}, A)[symbol] != 7 || objectKeys(nativeAssign({}, B)).join('') != alphabet;
-}) ? function assign(target, source) { // eslint-disable-line no-unused-vars
+}) ? function assign(target, source) { // eslint-disable-line no-unused-vars -- required for `.length`
   var T = toObject(target);
   var argumentsLength = arguments.length;
   var index = 1;

packages/core-js/internals/object-create.js

@@ -52,7 +52,7 @@ var NullProtoObjectViaIFrame = function () {
 var activeXDocument;
 var NullProtoObject = function () {
   try {
-    /* global ActiveXObject */
+    /* global ActiveXObject -- old IE */
     activeXDocument = document.domain && new ActiveXObject('htmlfile');
   } catch (error) { /* ignore */ }
   NullProtoObject = activeXDocument ? NullProtoObjectViaActiveX(activeXDocument) : NullProtoObjectViaIFrame();

packages/core-js/internals/object-prototype-accessors-forced.js

@@ -7,7 +7,7 @@ var fails = require('../internals/fails');
 module.exports = IS_PURE || !fails(function () {
   var key = Math.random();
   // In FF throws only define methods
-  // eslint-disable-next-line no-undef, no-useless-call
+  // eslint-disable-next-line no-undef, no-useless-call -- required for testing
   __defineSetter__.call(null, key, function () { /* empty */ });
   delete global[key];
 });

packages/core-js/internals/object-set-prototype-of.js

@@ -1,10 +1,10 @@
+/* eslint-disable no-proto -- safe */
 var anObject = require('../internals/an-object');
 var aPossiblePrototype = require('../internals/a-possible-prototype');
 
 // `Object.setPrototypeOf` method
 // https://tc39.es/ecma262/#sec-object.setprototypeof
 // Works with __proto__ only. Old v8 can't work with null proto objects.
-/* eslint-disable no-proto */
 module.exports = Object.setPrototypeOf || ('__proto__' in {} ? function () {
   var CORRECT_SETTER = false;
   var test = {};

packages/core-js/internals/range-iterator.js

@@ -40,7 +40,7 @@ var $RangeIterator = createIteratorConstructor(function RangeIterator(start, end
   if (step === Infinity || step === -Infinity || (step === zero && start !== end)) {
     throw new RangeError(INCORRECT_RANGE);
   }
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   var hitsEnd = start != start || end != end || step != step || (end > start) !== (step > zero);
   setInternalState(this, {
     type: RANGE_ITERATOR,

packages/core-js/internals/same-value-zero.js

@@ -1,6 +1,6 @@
 // `SameValueZero` abstract operation
 // https://tc39.es/ecma262/#sec-samevaluezero
 module.exports = function (x, y) {
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   return x === y || x != x && y != y;
 };

packages/core-js/internals/same-value.js

@@ -1,6 +1,6 @@
 // `SameValue` abstract operation
 // https://tc39.es/ecma262/#sec-samevalue
 module.exports = Object.is || function is(x, y) {
-  // eslint-disable-next-line no-self-compare
+  // eslint-disable-next-line no-self-compare -- NaN check
   return x === y ? x !== 0 || 1 / x === 1 / y : x != x && y != y;
 };

packages/core-js/internals/string-pad-webkit-bug.js

@@ -1,5 +1,5 @@
 // https://github.com/zloirock/core-js/issues/280
 var userAgent = require('../internals/engine-user-agent');
 
-// eslint-disable-next-line unicorn/no-unsafe-regex
+// eslint-disable-next-line unicorn/no-unsafe-regex -- safe
 module.exports = /Version\/10\.\d+(\.\d+)?( Mobile\/\w+)? Safari\//.test(userAgent);

packages/core-js/internals/string-punycode-to-ascii.js

@@ -74,7 +74,7 @@ var adapt = function (delta, numPoints, firstTime) {
  * Converts a string of Unicode symbols (e.g. a domain name label) to a
  * Punycode string of ASCII-only symbols.
  */
-// eslint-disable-next-line  max-statements
+// eslint-disable-next-line  max-statements -- TODO
 var encode = function (input) {
   var output = [];