@automattic/eslint-config-target-es 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2024-08-29
+### Added
+- Add mapping for `es-x/no-regexp-duplicate-named-capturing-groups`. [#39005]
+- Support eslint flat configs (`eslint.config.js`). [#37855]
+- Updated `eslint-plugin-es-x` adds additional rules: `es-x/no-arraybuffer-prototype-transfer`, `es-x/no-object-map-groupby`, `es-x/no-promise-withresolvers`, `es-x/no-resizable-and-growable-arraybuffers`, `es-x/no-set-prototype-difference`, `es-x/no-set-prototype-intersection`, `es-x/no-set-prototype-isdisjointfrom`, `es-x/no-set-prototype-issubsetof`, `es-x/no-set-prototype-issupersetof`, `es-x/no-set-prototype-symmetricdifference`, and `es-x/no-set-prototype-union`. [#37830]
+
+### Changed
+- Updated package dependencies. [#35608] [#36095] [#36325] [#36585] [#36760] [#37147] [#37379] [#37669] [#37828] [#37830] [#38132] [#38662] [#39002]
+
+## [2.1.0] - 2024-02-07
+### Added
+- All versions indicated by browserslist are now checked, not just the lowest. Added `getAllBrowsers` function to support this. [#31658]
+- Support for more complex MDN data:
+  * Multiple support statements are now all checked. Previously only the first (most recent) was, which may have missed cases where support was backported.
+  * `version_removed` is now checked.
+  * Ranged versions (≤) are now handled.
+  * `prefix`, `alternative_name`, and `flags` now indicate (possible) lack of support. [#31658]
+
+### Changed
+- Updated package dependencies.
+
+### Deprecated
+- Deprecated `getBrowsers` function in favor of the new `getAllBrowsers`. [#31658]
+
+### Fixed
+- Apparently MDN data considers "preview" a version, but didn't think that worth documenting. Handle it. [#31816]
+
 ## [2.0.0] - 2023-06-26
 ### Changed
 - As `eslint-plugin-es` appears to be abandoned, change to using `eslint-plugin-es-x`. [#31556]
@@ -41,6 +68,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial release.
 
+[2.2.0]: https://github.com/Automattic/eslint-config-target-es/compare/2.1.0...2.2.0
+[2.1.0]: https://github.com/Automattic/eslint-config-target-es/compare/2.0.0...2.1.0
 [2.0.0]: https://github.com/Automattic/eslint-config-target-es/compare/1.0.6...2.0.0
 [1.0.6]: https://github.com/Automattic/eslint-config-target-es/compare/1.0.5...1.0.6
 [1.0.5]: https://github.com/Automattic/eslint-config-target-es/compare/1.0.4...1.0.5

package/README.md

@@ -14,30 +14,30 @@ npm install --save-dev eslint eslint-plugin-es-x @automattic/eslint-config-targe
 
 First, you'll probably want to set up a [browserslist] configuration.
 
-Then you can use this like any other sharable config in your `.eslintrc.*` file. Three configurations are offered.
+Then you can use this like any other sharable config in your `eslint.config.js` or `.eslintrc.*` file. Three configurations are offered.
 
-To check only for language features, such as nullish coalescing, your eslintrc might look like
-```js
-{
-	extends: [ '@automattic/eslint-config-target-es/language' ],
-}
-```
+* To check only for language features, such as nullish coalescing, use the 'language' config.
+* To check only for builtins, such as Promise, WeakRef, and various features of RegExp, use the 'builtins' config.
+* To check both, use the 'all' config.
 
-To check only for builtins, such as Promise, WeakRef, and various features of RegExp, your eslintrc might look like
+For `eslint.config.js`, that might look like this:
 ```js
-{
-	extends: [ '@automattic/eslint-config-target-es/builtins' ],
-}
+import eslintConfigTargetEs from '@automattic/eslint-config-target-es/flat/language';
+
+export default [
+	eslintConfigTargetEs,
+	// etc
+];
 ```
 
-To check both, your eslintrc might look like
+while for eslintrc you'd do like
 ```js
 {
-	extends: [ '@automattic/eslint-config-target-es/all' ],
+	extends: [ '@automattic/eslint-config-target-es/rc/language' ],
 }
 ```
 
-For least surprise, omitting any suffix is the same as `/all`.
+For backwards compatibility, the eslintrc configs may also be accessed without the `/rc/` path component (e.g. as `@automattic/eslint-config-target-es/language`), and `@automattic/eslint-config-target-es` is equivalent to `@automattic/eslint-config-target-es/rc/all`.
 
 ### Checking built files
 
@@ -45,7 +45,7 @@ If you want to check your built files to make sure you didn't omit transpiling a
 ```js
 module.exports = {
 	root: true,
-	extends: [ '@automattic/eslint-config-target-es/language' ],
+	extends: [ '@automattic/eslint-config-target-es/rc/language' ],
 	env: {
 		// Whatever environments you need.
 	},
@@ -57,14 +57,20 @@ eslint --no-eslintrc --no-inline-config --config validate-es.config.js --no-igno
 ```
 to avoid your standard eslintrc and eslintignore and to avoid errors from any inline directives.
 
+Something similar can be done for flat config.
+
 ### Advanced usage
 
 You can import or require `@automattic/eslint-config-target-es/functions` to gain access to some functions that can be used to build your own configuration.
 
-As browserslist and MDN use different browser codes, `getBrowsers( { query: } )` will take a browserslist query and return an object with the MDN browser codes and the minimum matched version for each.
+As browserslist and MDN use different browser codes, `getAllBrowsers( { query: } )` will take a browserslist query and return an object with the MDN browser codes and the matched versions for each.
 
 `getRules( { query:, builtins: } )` will return the rules config. Set `builtins` true for "builtins", false for "language", or null/undefined for "all".
 
+### Caveats
+
+Some browsers supported by browserslist are not availble in the MDN data (e.g. Opera Mini) or are no longer being updated (e.g. Internet Explorer). In cases like these where no data is available, features are assumed to be supported. Set the environment variable `DEBUG=@automattic/eslint-config-target-es:warn` to generate messages when this happens.
+
 ## Security
 
 Need to report a security vulnerability? Go to [https://automattic.com/security/](https://automattic.com/security/) or directly to our security bug bounty site [https://hackerone.com/automattic](https://hackerone.com/automattic).

package/SECURITY.md

@@ -4,11 +4,20 @@ Full details of the Automattic Security Policy can be found on [automattic.com](
 
 ## Supported Versions
 
-Generally, only the latest version of Jetpack has continued support. If a critical vulnerability is found in the current version of Jetpack, we may opt to backport any patches to previous versions. 
+Generally, only the latest version of Jetpack and its associated plugins have continued support. If a critical vulnerability is found in the current version of a plugin, we may opt to backport any patches to previous versions. 
 
 ## Reporting a Vulnerability
 
-[Jetpack](https://jetpack.com/) is an open-source plugin for WordPress. Our HackerOne program covers the plugin software, as well as a variety of related projects and infrastructure.
+Our HackerOne program covers the below plugin software, as well as a variety of related projects and infrastructure:
+
+* [Jetpack](https://jetpack.com/)
+* Jetpack Backup
+* Jetpack Boost
+* Jetpack CRM
+* Jetpack Protect
+* Jetpack Search
+* Jetpack Social
+* Jetpack VideoPress
 
 **For responsible disclosure of security issues and to be eligible for our bug bounty program, please submit your report via the [HackerOne](https://hackerone.com/automattic) portal.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/eslint-config-target-es",
-	"version": "2.0.0",
+	"version": "2.2.0",
 	"description": "ESLint sharable config to activate eslint-plugin-es checks based on browserslist targets.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/eslint-config-target-es/README.md#readme",
 	"bugs": {
@@ -17,26 +17,39 @@
 		"test": "jest tests"
 	},
 	"dependencies": {
-		"@mdn/browser-compat-data": "5.2.66",
+		"@mdn/browser-compat-data": "5.5.47",
 		"browserslist": "^4.17.6",
 		"debug": "^4.3.2",
 		"semver": "^7.3.5"
 	},
 	"devDependencies": {
-		"@wordpress/browserslist-config": "5.18.0",
-		"eslint": "8.39.0",
-		"eslint-plugin-es-x": "7.1.0",
-		"jest": "29.4.3"
+		"@wordpress/browserslist-config": "6.5.0",
+		"eslint": "8.57.0",
+		"eslint-plugin-es-x": "7.8.0",
+		"globals": "15.4.0",
+		"jest": "29.7.0"
 	},
 	"peerDependencies": {
 		"eslint": ">=4.19.1",
-		"eslint-plugin-es-x": "^7.1.0"
+		"eslint-plugin-es-x": "^7.6.0",
+		"globals": ">=15.4.0"
+	},
+	"peerDependenciesMeta": {
+		"globals": {
+			"optional": true
+		}
 	},
 	"exports": {
-		".": "./src/configs/all.js",
-		"./language": "./src/configs/language.js",
-		"./builtins": "./src/configs/builtins.js",
-		"./all": "./src/configs/all.js",
+		".": "./src/eslintrc/all.js",
+		"./language": "./src/eslintrc/language.js",
+		"./builtins": "./src/eslintrc/builtins.js",
+		"./all": "./src/eslintrc/all.js",
+		"./rc/language": "./src/eslintrc/language.js",
+		"./rc/builtins": "./src/eslintrc/builtins.js",
+		"./rc/all": "./src/eslintrc/all.js",
+		"./flat/language": "./src/flatconfig/language.js",
+		"./flat/builtins": "./src/flatconfig/builtins.js",
+		"./flat/all": "./src/flatconfig/all.js",
 		"./functions": "./src/funcs.js"
 	}
 }

package/src/flatconfig/all.js

@@ -0,0 +1,6 @@
+const { getRules } = require( '../funcs' );
+
+module.exports = {
+	...require( './base' ),
+	rules: getRules(),
+};

package/src/flatconfig/base.js

@@ -0,0 +1,21 @@
+const esx = require( 'eslint-plugin-es-x' );
+
+const flatBase = {
+	plugins: {
+		'es-x': esx,
+	},
+	languageOptions: {
+		ecmaVersion: 2022,
+	},
+};
+
+try {
+	const globals = require( 'globals' );
+	if ( globals?.es2022 ) {
+		flatBase.languageOptions.globals = globals.es2022;
+	}
+} catch ( e ) {
+	// `globals` is optional.
+}
+
+module.exports = flatBase;

package/src/flatconfig/builtins.js

@@ -0,0 +1,6 @@
+const { getRules } = require( '../funcs' );
+
+module.exports = {
+	...require( './base' ),
+	rules: getRules( { builtins: true } ),
+};

package/src/flatconfig/language.js

@@ -0,0 +1,6 @@
+const { getRules } = require( '../funcs' );
+
+module.exports = {
+	...require( './base' ),
+	rules: getRules( { builtins: false } ),
+};

package/src/funcs.js

@@ -1,22 +1,20 @@
-const mdn = require( '@mdn/browser-compat-data' );
 const browserslist = require( 'browserslist' );
 const debug = require( 'debug' );
 const { rules: esRules } = require( 'eslint-plugin-es-x' );
 const semver = require( 'semver' );
 const browsersMap = require( './browsersMap.js' );
-const rulesMap = require( './rulesMap.js' );
+const { needsCheck } = require( './needsCheck.js' );
 
 const warn = debug( '@automattic/eslint-config-target-es:warn' );
-const debuglog = debug( '@automattic/eslint-config-target-es:debug' );
 
 /**
  * Get the list of supported browsers.
  *
- * @param {object} options - Options.
+ * @param {object} options       - Options.
  * @param {string} options.query - Browserslist query.
- * @returns {object} Browsers mapped to versions.
+ * @return {object} Browsers mapped to arrays of versions.
  */
-function getBrowsers( options = {} ) {
+function getAllBrowsers( options = {} ) {
 	const browsers = {};
 	for ( const b of browserslist( options.query ) ) {
 		const m = b.match( /^([a-z_]+) (all|[0-9.]+)(-.*)?$/ );
@@ -33,104 +31,41 @@ function getBrowsers( options = {} ) {
 			continue;
 		}
 		const ver = m[ 2 ] === 'all' ? '0.0.0' : semver.coerce( m[ 2 ] ).version;
-		if ( typeof browsers[ browser ] === 'undefined' || semver.lt( ver, browsers[ browser ] ) ) {
-			browsers[ browser ] = ver;
-		}
+		browsers[ browser ] ||= [];
+		browsers[ browser ].push( ver );
+		browsers[ browser ].sort( semver.compare );
 	}
 	return browsers;
 }
 
 /**
- * Test if a rule needs to be checked.
+ * Get the list of supported browsers.
  *
- * @param {string} rule - Rule.
- * @param {object} browsers - Browsers targeted.
- * @param {object} options - Options.
- * @param {boolean|null} options.builtins - If true, only rules with "javascript.builtins" paths are checked. If false, such rules are not checked. If null/undefined, all may be checked.
- * @returns {boolean} Whether the rule needs to be checked.
+ * @deprecated since 2.1.0. Use getAllBrowsers instead.
+ * @param {object} options       - Options.
+ * @param {string} options.query - Browserslist query.
+ * @return {object} Browsers mapped to minimum versions.
  */
-// eslint-disable-next-line no-unused-vars
-function needsCheck( rule, browsers, options = {} ) {
-	let paths = rulesMap[ rule ];
-	if ( paths === true || paths === false ) {
-		return paths;
-	}
-	if ( ! Array.isArray( paths ) ) {
-		paths = [ paths ];
-	}
-
-	if (
-		options.builtins === false &&
-		paths.some( path => path.startsWith( 'javascript.builtins.' ) )
-	) {
-		return false;
-	}
-	if (
-		options.builtins === true &&
-		! paths.some( path => path.startsWith( 'javascript.builtins.' ) )
-	) {
-		return false;
-	}
-
-	path: for ( const path of paths ) {
-		let data = mdn;
-		for ( const k of path.split( '.' ) ) {
-			data = data[ k ];
-			if ( ! data ) {
-				warn( `Invalid feature map for rule ${ rule }: ${ path } does not exist` );
-				continue path;
-			}
-		}
-		if ( ! data.__compat || ! data.__compat.support ) {
-			warn( `Invalid feature map for rule ${ rule }: No data at ${ path }` );
-			continue path;
-		}
-
-		browser: for ( const browser of Object.keys( browsers ) ) {
-			if ( ! data.__compat.support[ browser ] ) {
-				debuglog( `No support data for ${ browser } for rule ${ rule } (${ path }), skipping` );
-				continue browser;
-			}
-			let support = data.__compat.support[ browser ];
-			if ( Array.isArray( support ) ) {
-				support = support[ 0 ];
-			}
-
-			if ( support.version_added === null ) {
-				debuglog( `No support data for ${ browser } for rule ${ rule } (${ path }), skipping` );
-				continue browser;
-			} else if ( support.version_added === false ) {
-				debuglog( `${ browser } needs check for ${ rule } (${ path })` );
-				return true;
-			} else if ( support.version_added === true ) {
-				continue browser;
-			} else if ( semver.gt( semver.coerce( support.version_added ), browsers[ browser ] ) ) {
-				debuglog(
-					`${ browser } < ${ support.version_added } needs check for ${ rule } (${ path }); we have ${ browsers[ browser ] }`
-				);
-				return true;
-			} else if ( support.partial_implementation ) {
-				debuglog(
-					`${ browser } needs check for ${ rule } (${ path }) due to partial implementation`
-				);
-				return true;
-			}
-		}
+function getBrowsers( options = {} ) {
+	warn( 'getBrowsers is deprecated. Use getAllBrowsers instead.' );
+	const browsers = getAllBrowsers( options );
+	const ret = {};
+	for ( const k of Object.keys( browsers ) ) {
+		ret[ k ] = browsers[ k ][ 0 ];
 	}
-
-	return false;
+	return ret;
 }
 
 /**
  * Get the es-x rule configurations.
  *
- * @param {object} options - Options.
+ * @param {object}       options          - Options.
  * @param {boolean|null} options.builtins - If true, only rules with "javascript.builtins" paths are checked. If false, such rules are not checked. If null/undefined, all may be checked.
- * @param {string} options.query - Browserslist query.
- * @returns {object} Rules configuration.
+ * @param {string}       options.query    - Browserslist query.
+ * @return {object} Rules configuration.
  */
 function getRules( options = {} ) {
-	const browsers = getBrowsers( options );
+	const browsers = getAllBrowsers( options );
 	const ret = {};
 	for ( const rule of Object.keys( esRules ) ) {
 		ret[ `es-x/${ rule }` ] = needsCheck( rule, browsers, options ) ? 2 : 0;
@@ -139,6 +74,7 @@ function getRules( options = {} ) {
 }
 
 module.exports = {
+	getAllBrowsers,
 	getBrowsers,
 	getRules,
 };

package/src/needsCheck.js

@@ -0,0 +1,151 @@
+const mdn = require( '@mdn/browser-compat-data' );
+const debug = require( 'debug' );
+const semver = require( 'semver' );
+const rulesMap = require( './rulesMap.js' );
+
+const warn = debug( '@automattic/eslint-config-target-es:warn' );
+const debuglog = debug( '@automattic/eslint-config-target-es:debug' );
+
+/**
+ * Test if a rule needs to be checked.
+ *
+ * @param {string}       rule             - Rule.
+ * @param {object}       browsers         - Browsers targeted.
+ * @param {object}       options          - Options.
+ * @param {boolean|null} options.builtins - If true, only rules with "javascript.builtins" paths are checked. If false, such rules are not checked. If null/undefined, all may be checked.
+ * @return {boolean} Whether the rule needs to be checked.
+ */
+function needsCheck( rule, browsers, options = {} ) {
+	let paths = rulesMap[ rule ];
+	if ( paths === true || paths === false ) {
+		return paths;
+	}
+	if ( paths === undefined ) {
+		warn( `No feature map for rule ${ rule }` );
+		return false;
+	}
+	if ( ! Array.isArray( paths ) ) {
+		paths = [ paths ];
+	}
+
+	if (
+		options.builtins === false &&
+		paths.some( path => path.startsWith( 'javascript.builtins.' ) )
+	) {
+		return false;
+	}
+	if (
+		options.builtins === true &&
+		! paths.some( path => path.startsWith( 'javascript.builtins.' ) )
+	) {
+		return false;
+	}
+
+	const semver000 = semver.coerce( '0.0.0' );
+
+	path: for ( const path of paths ) {
+		let data = mdn;
+		for ( const k of path.split( '.' ) ) {
+			data = data[ k ];
+			if ( ! data ) {
+				warn( `Invalid feature map for rule ${ rule }: ${ path } does not exist` );
+				continue path;
+			}
+		}
+		if ( ! data.__compat || ! data.__compat.support ) {
+			warn( `Invalid feature map for rule ${ rule }: No data at ${ path }` );
+			continue path;
+		}
+
+		browser: for ( const browser of Object.keys( browsers ) ) {
+			if ( ! data.__compat.support[ browser ] ) {
+				warn( `No support data for ${ browser } for rule ${ rule } (${ path }), skipping` );
+				continue browser;
+			}
+
+			const supports = Array.isArray( data.__compat.support[ browser ] )
+				? data.__compat.support[ browser ]
+				: [ data.__compat.support[ browser ] ];
+			const vers = Array.isArray( browsers[ browser ] )
+				? browsers[ browser ]
+				: [ browsers[ browser ] ];
+
+			version: for ( const ver of vers ) {
+				const results = [];
+				support: for ( const support of supports ) {
+					if ( support.version_added === null ) {
+						continue support;
+					}
+
+					if ( support.version_added === false ) {
+						results.push( 'no support' );
+						continue support;
+					}
+					if ( support.version_added === 'preview' ) {
+						results.push( 'added version is "preview"' );
+						continue support;
+					}
+
+					let added, removed;
+					if ( support.version_added === true ) {
+						added = semver000;
+					} else {
+						added = support.version_added.startsWith( '≤' )
+							? semver000
+							: semver.coerce( support.version_added );
+					}
+					if ( support.version_removed === true ) {
+						removed = semver000;
+					} else if (
+						typeof support.version_removed === 'string' &&
+						support.version_removed !== 'preview'
+					) {
+						removed = support.version_removed.startsWith( '≤' )
+							? semver000
+							: semver.coerce( support.version_removed );
+					}
+
+					const range = removed ? `${ added } – <${ removed }` : `>= ${ added }`;
+
+					if ( semver.gt( added, ver ) || ( removed && semver.lte( removed, ver ) ) ) {
+						results.push( `outside range ${ range }` );
+					} else if ( support.partial_implementation ) {
+						results.push( `partial implementation for ${ range }` );
+					} else if ( support.prefix ) {
+						results.push( `prefixed implementation for ${ range }` );
+					} else if ( support.alternative_name ) {
+						results.push( `alternatively named implementation for ${ range }` );
+					} else if ( support.flags ) {
+						results.push( `flagged implementation for ${ range }` );
+					} else {
+						// It's good! Check the next version.
+						continue version;
+					}
+				}
+
+				// If there was no support data at all...
+				if ( results.length === 0 ) {
+					warn( `No support data for ${ browser } for rule ${ rule } (${ path }), skipping` );
+					continue browser;
+				}
+
+				// If no support entry hit the "It's good" case, it's no good. Log the reasons.
+				// If there are reasons other than "outside range", skip any "outside range" as irrelevant.
+				let results2 = results.filter( v => ! v.startsWith( 'outside range' ) );
+				if ( results2.length === 0 ) {
+					results2 = results;
+				}
+				debuglog(
+					`${ browser } ${ ver } needs check for ${ rule } (${ path }); ${ results2.join( '; ' ) }`
+				);
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+module.exports = {
+	needsCheck,
+};

package/src/rulesMap.js

@@ -1,8 +1,36 @@
 // Map of eslint-plugin-es-x rules to MDN compat-data paths.
 // Values are either a path, an array of paths, true to always enable the rule, or false to always disable it.
 module.exports = {
-	// ?
+	// ES2025
+	'no-regexp-duplicate-named-capturing-groups':
+		'javascript.regular_expressions.named_capturing_group.duplicate_named_capturing_groups',
+
+	// ES2024
+	'no-arraybuffer-prototype-transfer': 'javascript.builtins.ArrayBuffer.transfer',
 	'no-atomics-waitasync': 'javascript.builtins.Atomics.waitAsync',
+	'no-object-map-groupby': [
+		'javascript.builtins.Map.groupBy',
+		'javascript.builtins.Object.groupBy',
+	],
+	'no-promise-withresolvers': 'javascript.builtins.Promise.withResolvers',
+	'no-regexp-v-flag': 'javascript.builtins.RegExp.unicodeSets',
+	'no-resizable-and-growable-arraybuffers': [
+		'javascript.builtins.ArrayBuffer.ArrayBuffer.maxByteLength_option',
+		'javascript.builtins.ArrayBuffer.maxByteLength',
+		'javascript.builtins.ArrayBuffer.resizable',
+		'javascript.builtins.ArrayBuffer.resize',
+		'javascript.builtins.SharedArrayBuffer.SharedArrayBuffer.maxByteLength_option',
+		'javascript.builtins.SharedArrayBuffer.grow',
+		'javascript.builtins.SharedArrayBuffer.growable',
+		'javascript.builtins.SharedArrayBuffer.maxByteLength',
+	],
+	'no-set-prototype-difference': 'javascript.builtins.Set.difference',
+	'no-set-prototype-intersection': 'javascript.builtins.Set.intersection',
+	'no-set-prototype-isdisjointfrom': 'javascript.builtins.Set.isDisjointFrom',
+	'no-set-prototype-issubsetof': 'javascript.builtins.Set.isSubsetOf',
+	'no-set-prototype-issupersetof': 'javascript.builtins.Set.isSupersetOf',
+	'no-set-prototype-symmetricdifference': 'javascript.builtins.Set.symmetricDifference',
+	'no-set-prototype-union': 'javascript.builtins.Set.union',
 	'no-string-prototype-iswellformed-towellformed': [
 		'javascript.builtins.String.isWellFormed',
 		'javascript.builtins.String.toWellFormed',