@automattic/eslint-plugin-wpvip 0.4.11 → 0.4.12

package/README.md

@@ -1,6 +1,6 @@
 # WordPress VIP ESLint plugin
 
-This is an ESLint plugin to provide WordPress VIP's (internal) JavaScript and TypeScript coding standards. It extends [`@wordpress/eslint-plugin`](https://github.com/WordPress/gutenberg/tree/trunk/packages/eslint-plugin).
+This is an ESLint plugin to provide WordPress VIP's (internal) JavaScript and TypeScript coding standards. It is inspired by and borrows from [`@wordpress/eslint-plugin`](https://github.com/WordPress/gutenberg/tree/trunk/packages/eslint-plugin).
 
 ## Installation
 
@@ -12,104 +12,85 @@ npm install --save-dev eslint @automattic/eslint-plugin-wpvip
 
 ## Configuration
 
-Create an `.eslintrc.js` file with your desired configs. **Note:** The `init` file allows you to avoid installing peer dependencies (available from `v0.5.0`).
+Create an `.eslintrc.js` file. **Note:** The `init` file allows you to avoid installing peer dependencies (available from `v0.5.0`).
 
 ```js
 require( '@automattic/eslint-plugin-wpvip/init' );
 
 module.exports = {
 	extends: [
-		'plugin:@automattic/wpvip/base',
-	]
-}
+		'plugin:@automattic/wpvip/recommended',
+	],
+};
 ```
 
-And that's it! Code editors that are configured to work with ESLint will automatically pick up the rules and flag any errors or warnings.
-
-Tip: Set up a `lint` npm script in `package.json`:
-
-```json
-"scripts": {
-  "lint": "eslint ."
-}
-```
+And that's it! It works automatically with most Babel and TypeScript projects. Code editors that are configured to work with ESLint will automatically pick up the rules and flag any errors or warnings.
 
 You may also wish to define an `.eslintignore` file if there are files or paths that you do not want to lint.
 
-## TypeScript
+## Recommended config
 
-TypeScript rules are automatically added whenever your project has installed the [`typescript` NPM package]() as a dependency.
+The "recommended" config includes rules for JavaScript, TypeScript, Jest, and React, including rules related to formatting and white space. It is intended to be strict! Opinionated defaults keep our codebases consistent and reduce the friction we experience when context-switching between projects.
 
-## Prettier
+If your project has installed [Prettier](https://prettier.io/) as a dependency, then many formatting tasks will be delegated to it (via `eslint-plugin-prettier`). You are encouraged to define your own [`.prettierrc` configuration file](https://prettier.io/docs/en/configuration.html) to fine-tune your project’s formatting.
 
-Prettier integration with ESLint is automatically enabled. Further, by default, this plugin provides the [WordPress prettier config](https://github.com/WordPress/gutenberg/blob/605aeb0f4f7d2225120e498f95ae27b9f56d77a3/packages/prettier-config/lib/index.js). You can define your own [`.prettierrc` configuration file](https://prettier.io/docs/en/configuration.html), which will be merged with the default. The following `.prettierrc` will use spaces for indentation instead of tabs:
+Of course, this recommended config may not be ideal for every project, so feel free to "build your own" using the available modular configs. The recommended config is equivalent to:
 
-```json
-{
-  "useTabs": false
-}
+```js
+module.exports = {
+	extends: [
+		'plugin:@automattic/wpvip/javascript',
+		'plugin:@automattic/wpvip/typescript', // when "typescript" is installed
+		'plugin:@automattic/wpvip/formatting',
+		'plugin:@automattic/wpvip/testing',    // when "jest" is installed
+		'plugin:@automattic/wpvip/react',      // when "react" is installed
+		'plugin:@automattic/wpvip/prettier',   // when "prettier" is installed
+	],
+};
 ```
 
-If you wish to disable the automatic Prettier integration, add the `prettier-off` config to your `.eslintrc.js`:
-
-```json
-{
-	"extends": [
-		"plugin:@automattic/wpvip/base",
-		"plugin:@automattic/wpvip/prettier-off"
-	]
-}
-```
+Note that the order of configs can matter, since they can contain overrides. It is particularly important to add the `prettier` config last.
 
 ## CLI
 
 The `cli` config allows certain behaviors that are usually against best practice but are useful in a codebase that produces a CLI tool:
 
-```json
-{
-	"extends": [
-		"plugin:@automattic/wpvip/base",
-		"plugin:@automattic/wpvip/cli"
-	]
-}
+```js
+module.exports = {
+	extends: [
+		'plugin:@automattic/wpvip/recommended',
+		'plugin:@automattic/wpvip/cli',
+	],
+};
 ```
 
-If your project is not a CLI tool but calls `console` or `process` methods occasionally, don't use this config—just add ignore statements in those few spots.
+If your project is not a CLI tool but calls `console` or `process` methods occasionally, you probably don't need this config. Instead, disable those rules only where necessary and include an explanation:
+
+```js
+// Intentionally exiting because we have observed an unrecoverable error.
+// eslint-disable-next-line no-process-exit
+process.exit( 1 );
+```
 
 ## JSDoc
 
-The `base` config includes rules related to enforce [JSDoc](https://jsdoc.app/) best practices, but they are not triggered if your code does not provide `@param` or `@return` markers:
+JSDoc is considered optional, especially compared to better alternatives like TypeScript and OpenAPI documentation. If you want to enforce the use of JSDoc, use the `jsdoc` config:
 
 ```js
-/**
- * No rules are triggered for this docblock, because there are no param or
- * return markers
- */
- function myFunc1() {}
-
-/**
- * Rules *are* triggered for this docblock.
- *
- * @param myArg
- */
- function myFunc2(myArg) {}
+module.exports = {
+	extends: [
+		'plugin:@automattic/wpvip/recommended',
+		'plugin:@automattic/wpvip/jsdoc',
+	],
+};
 ```
 
-If you want to enforce the use of JSDoc, use the `jsdoc` config:
-
-```json
-{
-	"extends": [
-		"plugin:@automattic/wpvip/base",
-		"plugin:@automattic/wpvip/jsdoc"
-	]
-}
-```
+Note that rules that require `@param` and `@return` types are relaxed in TypeScript files.
 
 ## "Weak" configs
 
-This plugin provides a few "weak" configs for legacy codebases that are working to transition to stronger standards. These configs downgrade select rules from the `base` config to warnings. Warnings will still be visible in code editors, but will not fail continous integration workflows.
+This plugin provides a few so-called "weak" configs for legacy codebases that are working to transition to stronger standards. These configs downgrade select rules from the `recommended` config to warnings. Warnings will still be visible in code editors and other outputs but will not fail continous integration workflows.
 
-These configs are intended for temporary use and should not be used long-term. We also do not recommend the use of tools like [eslines](https://github.com/Automattic/eslines) to ignore errors or warnings. While the intention is to prevent large-scale changes and transition slowly to stronger standards, the effect is usually that the transition stalls and stops completely.
+These configs are intended for temporary use and should not be used long-term. We also do not recommend the use of tools like [eslines](https://github.com/Automattic/eslines) to ignore errors or warnings. While the intention is to prevent large-scale changes and transition slowly to stronger standards, the effect is usually that the transition stalls and eventually stops completely.
 
-Two "weak" configs are available: `weak` and `weak-typescript`. While pull requests on this project are always welcome, please carefully consider whether adding rules to these configs is truly necessary.
+Three "weak" configs are available: `weak-javascript`, `weak-typescript`, and `weak-jest`. While pull requests on this project are always welcome, please carefully consider whether adding rules to these configs is truly necessary. Ideally, we work to remove rules from these configs until they are no longer needed.

package/configs/formatting.js

@@ -4,13 +4,13 @@ module.exports = {
 	 * disable errors, include a brief justification or reasoning.
 	 */
 	rules: {
-		'array-bracket-spacing': [ 'error', 'always' ],
+		'array-bracket-spacing': ['error', 'always'],
 
-		'arrow-parens': [ 'error', 'always' ],
+		'arrow-parens': ['error', 'always'],
 
 		'arrow-spacing': 'error',
 
-		'brace-style': [ 'error', '1tbs' ],
+		'brace-style': ['error', '1tbs'],
 
 		// Identifiers should be in camelCase. Object properties are excluded
 		// (including when destructuring) since they often come from external
@@ -23,24 +23,24 @@ module.exports = {
 			},
 		],
 
-		'comma-dangle': [ 'error', 'always-multiline' ],
+		'comma-dangle': ['error', 'always-multiline'],
 
 		'comma-spacing': 'error',
 
-		'comma-style': [ 'error', 'last' ],
+		'comma-style': ['error', 'last'],
 
-		'computed-property-spacing': [ 'error', 'always' ],
+		'computed-property-spacing': ['error', 'always'],
 
-		curly: [ 'error', 'all' ],
+		curly: ['error', 'all'],
 
 		'dot-notation': 'error',
 
 		// Files must end in a newline.
-		'eol-last': [ 'error', 'always' ],
+		'eol-last': ['error', 'always'],
 
 		'func-call-spacing': 'error',
 
-		indent: [ 'error', 'tab', { SwitchCase: 1 } ],
+		indent: ['error', 'tab', { SwitchCase: 1 }],
 
 		'key-spacing': 'error',
 
@@ -58,19 +58,19 @@ module.exports = {
 
 		'no-multi-str': 'error',
 
-		'no-multiple-empty-lines': [ 'error', { max: 1 } ],
+		'no-multiple-empty-lines': ['error', { max: 1 }],
 
 		'no-trailing-spaces': 'error',
 
 		'no-whitespace-before-property': 'error',
 
-		'object-curly-spacing': [ 'error', 'always' ],
+		'object-curly-spacing': ['error', 'always'],
 
 		'object-shorthand': 'error',
 
 		'operator-linebreak': 'error',
 
-		'padded-blocks': [ 'error', 'never' ],
+		'padded-blocks': ['error', 'never'],
 
 		// Arrow functions should be used for function arguments and callbacks.
 		'prefer-arrow-callback': 'warn',
@@ -81,30 +81,28 @@ module.exports = {
 			{ allowTemplateLiterals: true, avoidEscape: true },
 		],
 
-		'quote-props': [ 'error', 'as-needed' ],
+		'quote-props': ['error', 'as-needed'],
 
 		semi: 'error',
 
 		'semi-spacing': 'error',
 
-		'space-before-blocks': [ 'error', 'always' ],
+		'space-before-blocks': ['error', 'always'],
 
 		'space-before-function-paren': [
 			'error',
 			{ anonymous: 'never', named: 'never', asyncArrow: 'always' },
 		],
 
-		'space-in-parens': [ 'error', 'always' ],
+		'space-in-parens': ['error', 'always'],
 
 		'space-infix-ops': 'error',
 
-		'space-unary-ops': [ 'error', { overrides: { '!': true, yield: true } } ],
+		'space-unary-ops': ['error', { overrides: { '!': true, yield: true } }],
 
 		// Comments should always include consistent spacing for readability.
 		'spaced-comment': 'warn',
 
-		'template-curly-spacing': [ 'error', 'always' ],
-
+		'template-curly-spacing': ['error', 'always'],
 	},
 };
-

package/configs/index.js

@@ -1,14 +1,15 @@
 module.exports = {
-	base: require( './base' ),
-	cli: require( './cli' ),
-	formatting: require( './formatting' ),
-	javascript: require( './javascript' ),
-	jsdoc: require( './jsdoc' ),
-	prettier: require( './prettier' ),
-	react: require( './react' ),
-	testing: require( './testing' ),
-	typescript: require( './typescript' ),
-	'weak-javascript': require( './weak-javascript' ),
-	'weak-testing': require( './weak-testing' ),
-	'weak-typescript': require( './weak-typescript' ),
+	base: require('./javascript'), // synonym for javascript
+	cli: require('./cli'),
+	formatting: require('./formatting'),
+	javascript: require('./javascript'),
+	jsdoc: require('./jsdoc'),
+	prettier: require('./prettier'),
+	react: require('./react'),
+	recommended: require('./recommended'),
+	testing: require('./testing'),
+	typescript: require('./typescript'),
+	'weak-javascript': require('./weak-javascript'),
+	'weak-testing': require('./weak-testing'),
+	'weak-typescript': require('./weak-typescript'),
 };

package/configs/javascript.js

@@ -12,6 +12,8 @@ module.exports = {
 		node: true,
 	},
 
+	extends: ['plugin:json/recommended', 'plugin:security/recommended'],
+
 	parser: '@babel/eslint-parser',
 
 	parserOptions: {
@@ -22,15 +24,14 @@ module.exports = {
 	/**
 	 * Note: We must explicitly add this plugin to use our custom rules.
 	 */
-	plugins: [ '@automattic/wpvip', 'import' ],
+	plugins: ['@automattic/wpvip', 'import'],
 
 	/**
 	 * Please include a short description of the rule. For rules that downgrade or
 	 * disable errors, include a brief justification or reasoning.
 	 */
 	rules: {
-		// These rules are from eslint:recommended, but are enumerated here for
-		// visibility:
+		// BEGIN eslint:recommended, enumerated here for visibility:
 		// https://github.com/eslint/eslint/blob/main/packages/js/src/configs/eslint-recommended.js
 		'constructor-super': 'error',
 		'for-direction': 'error',
@@ -93,6 +94,7 @@ module.exports = {
 		'require-yield': 'error',
 		'use-isnan': 'error',
 		// 'valid-typeof': 'error', // extended below
+		// END eslint:recommended
 
 		// Async/await must not be used in a `.forEach` method, because the result
 		// will not be awaited in the outer scope.
@@ -137,7 +139,7 @@ module.exports = {
 
 		// Enforce Unix linebreaks. Included here and not in "formatting" since it
 		// is not controversial and helps with interchange.
-		'linebreak-style': [ 'error', 'unix' ],
+		'linebreak-style': ['error', 'unix'],
 
 		'no-alert': 'error',
 
@@ -149,7 +151,7 @@ module.exports = {
 
 		'no-caller': 'error',
 
-		'no-cond-assign': [ 'error', 'except-parens' ],
+		'no-cond-assign': ['error', 'except-parens'],
 
 		// `console.log` should not be used directly in code. Ideally, delegate to a
 		// logging function that logs on your behalf (and ignore this rule there).
@@ -161,7 +163,7 @@ module.exports = {
 
 		'no-else-return': 'error',
 
-		'no-empty': [ 'error', { allowEmptyCatch: true } ],
+		'no-empty': ['error', { allowEmptyCatch: true }],
 
 		'no-eq-null': 'error',
 
@@ -179,7 +181,7 @@ module.exports = {
 
 		'no-unused-expressions': 'error',
 
-		'no-unused-vars': [ 'error', { ignoreRestSiblings: true } ],
+		'no-unused-vars': ['error', { ignoreRestSiblings: true }],
 
 		'no-useless-computed-key': 'error',
 
@@ -189,9 +191,9 @@ module.exports = {
 
 		'no-var': 'error',
 
-		'one-var': [ 'error', 'never' ],
+		'one-var': ['error', 'never'],
 
-		'prefer-const': [ 'error', { destructuring: 'all' } ],
+		'prefer-const': ['error', { destructuring: 'all' }],
 
 		radix: 'error',
 
@@ -203,6 +205,6 @@ module.exports = {
 			},
 		],
 
-		'wrap-iife': [ 'error', 'any' ],
+		'wrap-iife': ['error', 'any'],
 	},
 };

package/configs/jsdoc.js

@@ -3,7 +3,7 @@
  * https://github.com/WordPress/gutenberg/blob/%40wordpress/eslint-plugin%4014.1.0/packages/eslint-plugin/configs/jsdoc.js
  */
 
-const globals = require( 'globals' );
+const globals = require('globals');
 
 /**
  * Helpful utilities that are globally defined and known to the TypeScript compiler.
@@ -41,7 +41,7 @@ const typescriptUtilityTypes = [
 ];
 
 module.exports = {
-	extends: [ 'plugin:jsdoc/recommended' ],
+	extends: ['plugin:jsdoc/recommended'],
 	settings: {
 		jsdoc: {
 			preferredTypes: {
@@ -61,9 +61,7 @@ module.exports = {
 					// Required to reference browser types because we don't have the `browser` environment enabled for the project.
 					// Here we filter out all browser globals that don't begin with an uppercase letter because those
 					// generally refer to window-level event listeners and are not a valid type to reference (e.g. `onclick`).
-					...Object.keys( globals.browser ).filter( ( key ) =>
-						/^[A-Z]/.test( key ),
-					),
+					...Object.keys(globals.browser).filter((key) => /^[A-Z]/.test(key)),
 					...typescriptUtilityTypes,
 					'void',
 					'JSX',
@@ -75,17 +73,14 @@ module.exports = {
 		'jsdoc/require-returns': 'off',
 		'jsdoc/require-yields': 'off',
 		'jsdoc/tag-lines': 'off',
-		'jsdoc/no-multi-asterisks': [
-			'error',
-			{ preventAtMiddleLines: false },
-		],
+		'jsdoc/no-multi-asterisks': ['error', { preventAtMiddleLines: false }],
 		'jsdoc/check-access': 'error',
 		'jsdoc/check-alignment': 'error',
 		'jsdoc/check-line-alignment': [
 			'error',
 			'always',
 			{
-				tags: [ 'param', 'arg', 'argument', 'property', 'prop' ],
+				tags: ['param', 'arg', 'argument', 'property', 'prop'],
 				preserveMainDescriptionPostDelimiter: true,
 			},
 		],

package/configs/jsx-ally.js

@@ -4,8 +4,8 @@
  */
 
 module.exports = {
-	extends: [ 'plugin:jsx-a11y/recommended' ],
-	plugins: [ 'jsx-a11y' ],
+	extends: ['plugin:jsx-a11y/recommended'],
+	plugins: ['jsx-a11y'],
 	rules: {
 		'jsx-a11y/label-has-associated-control': [
 			'error',

package/configs/prettier.js

@@ -4,8 +4,8 @@
  */
 
 module.exports = {
-	extends: [ 'plugin:prettier/recommended' ],
-	plugins: [ 'prettier' ],
+	extends: ['plugin:prettier/recommended'],
+	plugins: ['prettier'],
 	rules: {
 		'prettier/prettier': 'error',
 	},

package/configs/react.js

@@ -7,19 +7,23 @@ module.exports = {
 	extends: [
 		'plugin:react/recommended',
 		'plugin:react-hooks/recommended',
-		require( './jsx-ally' ),
+		require('./jsx-ally'),
 	],
+
 	parserOptions: {
 		ecmaFeatures: {
 			jsx: true,
 		},
 	},
+
 	settings: {
 		react: {
 			version: 'detect',
 		},
 	},
-	plugins: [ '@automattic/wpvip', 'react', 'react-hooks' ],
+
+	plugins: ['@automattic/wpvip', 'react', 'react-hooks'],
+
 	rules: {
 		'@automattic/wpvip/no-unused-vars-before-return': [
 			'error',
@@ -27,7 +31,9 @@ module.exports = {
 				excludePattern: '^use',
 			},
 		],
+
 		'react/display-name': 'off',
+
 		'react/jsx-curly-spacing': [
 			'error',
 			{
@@ -35,13 +41,21 @@ module.exports = {
 				children: true,
 			},
 		],
+
 		'react/jsx-equals-spacing': 'error',
-		'react/jsx-indent': [ 'error', 'tab' ],
-		'react/jsx-indent-props': [ 'error', 'tab' ],
+
+		'react/jsx-indent': ['error', 'tab'],
+
+		'react/jsx-indent-props': ['error', 'tab'],
+
 		'react/jsx-key': 'error',
+
 		'react/jsx-tag-spacing': 'error',
+
 		'react/no-children-prop': 'off',
+
 		'react/prop-types': 'off',
+
 		'react/react-in-jsx-scope': 'off',
 	},
 };

package/configs/recommended.js

@@ -0,0 +1,28 @@
+const debugLog = require('../utils/debug-log');
+const isPackageInstalled = require('../utils/is-package-installed');
+
+const config = {
+	extends: [require.resolve('./javascript')],
+};
+
+if (isPackageInstalled('typescript')) {
+	config.extends.push(require.resolve('./typescript'));
+}
+
+config.extends.push(require.resolve('./formatting'));
+
+if (isPackageInstalled('jest')) {
+	config.extends.push(require.resolve('./testing'));
+}
+
+if (isPackageInstalled('react')) {
+	config.extends.push(require.resolve('./react'));
+}
+
+if (isPackageInstalled('prettier')) {
+	config.extends.push(require.resolve('./prettier'));
+}
+
+debugLog(`Using the following configs:\n${config.extends.join('\n')}`);
+
+module.exports = config;

package/configs/testing.js

@@ -5,11 +5,11 @@
  */
 
 module.exports = {
-	extends: [ 'plugin:jest/recommended' ],
+	extends: ['plugin:jest/recommended'],
 
 	env: {
 		'jest/globals': true,
 	},
 
-	plugins: [ 'jest' ],
+	plugins: ['jest'],
 };

package/configs/typescript.js

@@ -4,7 +4,7 @@
  */
 
 module.exports = {
-	ignorePatterns: [ '**/*.d.ts' ],
+	ignorePatterns: ['**/*.d.ts'],
 
 	overrides: [
 		{
@@ -14,7 +14,7 @@ module.exports = {
 				'plugin:@typescript-eslint/strict',
 			],
 
-			files: [ '**/*.ts', '**/*.tsx' ],
+			files: ['**/*.ts', '**/*.tsx'],
 
 			parser: '@typescript-eslint/parser',
 
@@ -39,12 +39,12 @@ module.exports = {
 		},
 	],
 
-	plugins: [ '@typescript-eslint', 'jsdoc' ],
+	plugins: ['@typescript-eslint', 'jsdoc'],
 
 	settings: {
 		'import/resolver': {
 			node: {
-				extensions: [ '.js', '.jsx', '.ts', '.tsx' ],
+				extensions: ['.js', '.jsx', '.ts', '.tsx'],
 			},
 		},
 	},

package/configs/weak-javascript.js

@@ -10,7 +10,7 @@ module.exports = {
 	overrides: [
 		{
 			// Don't apply weak rules to TypeScript files.
-			files: [ '**/*.js', '**/*.jsx' ],
+			files: ['**/*.js', '**/*.jsx'],
 
 			/**
 			 * Downgrade rules from the base preset to "warn". Do not disable rules (set

package/configs/weak-testing.js

@@ -21,4 +21,3 @@ module.exports = {
 		'jest/no-standalone-expect': 'warn',
 	},
 };
-

package/configs/weak-typescript.js

@@ -5,9 +5,15 @@
  * you migrate an existing project to TypeScript.
  */
 module.exports = {
-	/**
-	 * Downgrade rules from the base preset to "warn". Do not disable rules (set
-	 * to "off"). If a rule is already set to a warning, do not disable it.
-	 */
-	rules: {},
+	overrides: [
+		{
+			files: ['**/*.ts', '**/*.tsx'],
+
+			/**
+			 * Downgrade rules from the base preset to "warn". Do not disable rules (set
+			 * to "off"). If a rule is already set to a warning, do not disable it.
+			 */
+			rules: {},
+		},
+	],
 };

package/index.js

@@ -1,4 +1,4 @@
 module.exports = {
-	configs: require( './configs' ),
-	rules: require( './rules' ),
+	configs: require('./configs'),
+	rules: require('./rules'),
 };

package/init.js

@@ -1 +1 @@
-require( '@rushstack/eslint-patch/modern-module-resolution' );
+require('@rushstack/eslint-patch/modern-module-resolution');

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@automattic/eslint-plugin-wpvip",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "ESLint plugin for internal WordPress VIP projects",
   "main": "index.js",
   "scripts": {
     "jest": "jest",
     "jest:update-snapshot": "jest --updateSnapshot",
     "link-plugin": "mkdir -p ./node_modules/@automattic; ln -fns $(pwd) ./node_modules/@automattic/eslint-plugin-wpvip",
-    "lint": "eslint .",
-    "test": "npm run link-plugin && npm run lint && jest"
+    "lint": "npm run link-plugin && eslint .",
+    "test": "jest"
   },
   "repository": {
     "type": "git",
@@ -29,14 +29,17 @@
     "@rushstack/eslint-patch": "1.2.0",
     "@typescript-eslint/eslint-plugin": "5.55.0",
     "@typescript-eslint/parser": "5.55.0",
+    "eslint-config-prettier": "8.7.0",
     "eslint-plugin-import": "2.27.5",
     "eslint-plugin-jest": "27.2.1",
     "eslint-plugin-jsdoc": "40.0.2",
     "eslint-plugin-json": "3.1.0",
     "eslint-plugin-jsx-a11y": "6.7.1",
+    "eslint-plugin-prettier": "4.2.1",
     "eslint-plugin-react": "7.32.2",
     "eslint-plugin-react-hooks": "4.6.0",
     "eslint-plugin-security": "1.7.1",
+    "find-package-json": "1.2.0",
     "globals": "13.20.0"
   },
   "peerDependencies": {
@@ -44,8 +47,6 @@
   },
   "devDependencies": {
     "eslint": "8.35.0",
-    "eslint-config-prettier": "8.7.0",
-    "eslint-plugin-eslint-plugin": "5.0.8",
     "jest": "29.5.0",
     "prettier": "2.8.4",
     "typescript": "4.9.5"

package/rules/dependency-group.js

@@ -17,7 +17,7 @@ module.exports = {
 		schema: [],
 		fixable: 'code',
 	},
-	create( context ) {
+	create(context) {
 		const comments = context.getSourceCode().getAllComments();
 
 		/**
@@ -45,8 +45,8 @@ module.exports = {
 		 *
 		 * @return {string} Expected comment node value.
 		 */
-		function getCommentValue( locality ) {
-			return `*\n * ${ locality } dependencies\n `;
+		function getCommentValue(locality) {
+			return `*\n * ${locality} dependencies\n `;
 		}
 
 		/**
@@ -57,10 +57,10 @@ module.exports = {
 		 *
 		 * @return {WPPackageLocality} Package locality.
 		 */
-		function getPackageLocality( source ) {
-			if ( source.startsWith( '.' ) ) {
+		function getPackageLocality(source) {
+			if (source.startsWith('.')) {
 				return 'Internal';
-			} else if ( source.startsWith( '@wordpress/' ) ) {
+			} else if (source.startsWith('@wordpress/')) {
 				return 'WordPress';
 			}
 
@@ -76,9 +76,9 @@ module.exports = {
 		 *
 		 * @return {boolean} Whether comment node satisfies locality.
 		 */
-		function isLocalityDependencyBlock( node, locality ) {
+		function isLocalityDependencyBlock(node, locality) {
 			const { type, value } = node;
-			if ( type !== 'Block' ) {
+			if (type !== 'Block') {
 				return false;
 			}
 
@@ -88,16 +88,16 @@ module.exports = {
 			// - Ending period
 			// - "Node" dependencies as an alias for External.
 
-			if ( locality === 'External' ) {
+			if (locality === 'External') {
 				locality = '(External|Node)';
 			}
 
 			// eslint-disable-next-line security/detect-non-literal-regexp
 			const pattern = new RegExp(
-				`^\\*?\\n \\* ${ locality } dependencies\\.?\\n $`,
-				'i',
+				`^\\*?\\n \\* ${locality} dependencies\\.?\\n $`,
+				'i'
 			);
-			return pattern.test( value );
+			return pattern.test(value);
 		}
 
 		/**
@@ -109,12 +109,12 @@ module.exports = {
 		 *
 		 * @return {boolean} Whether node occurs before reference.
 		 */
-		function isBefore( node, reference ) {
-			if ( ! node.range || ! reference.range ) {
+		function isBefore(node, reference) {
+			if (!node.range || !reference.range) {
 				return false;
 			}
 
-			return node.range[ 0 ] < reference.range[ 0 ];
+			return node.range[0] < reference.range[0];
 		}
 
 		/**
@@ -128,22 +128,22 @@ module.exports = {
 		 *
 		 * @return {WPDependencyBlockCorrection | undefined} Correction, if applicable.
 		 */
-		function getDependencyBlockCorrection( node, locality ) {
-			const value = getCommentValue( locality );
+		function getDependencyBlockCorrection(node, locality) {
+			const value = getCommentValue(locality);
 
-			for ( const comment of comments ) {
-				if ( ! isBefore( comment, node ) ) {
+			for (const comment of comments) {
+				if (!isBefore(comment, node)) {
 					// Exhausted options.
 					break;
 				}
 
-				if ( ! isLocalityDependencyBlock( comment, locality ) ) {
+				if (!isLocalityDependencyBlock(comment, locality)) {
 					// Not usable (either not an block comment, or not one
 					// matching a tolerable pattern).
 					continue;
 				}
 
-				if ( comment.value === value ) {
+				if (comment.value === value) {
 					// No change needed. (OK)
 					return;
 				}
@@ -159,7 +159,7 @@ module.exports = {
 			/**
 			 * @param {import('estree').Program} node Program node.
 			 */
-			Program( node ) {
+			Program(node) {
 				/**
 				 * The set of package localities which have been reported for
 				 * the current program. Each locality is reported at most one
@@ -181,29 +181,25 @@ module.exports = {
 				// Since we only care to enforce imports which occur at the
 				// top-level scope, match on Program and test its children,
 				// rather than matching the import nodes directly.
-				node.body.forEach( ( child ) => {
+				node.body.forEach((child) => {
 					/** @type {string} */
 					let source;
-					switch ( child.type ) {
+					switch (child.type) {
 						case 'ImportDeclaration':
-							source = /** @type {string} */ (
-								child.source.value
-							);
-							candidates.push( [ child, source ] );
+							source = /** @type {string} */ (child.source.value);
+							candidates.push([child, source]);
 							break;
 
 						case 'VariableDeclaration':
-							child.declarations.forEach( ( declaration ) => {
+							child.declarations.forEach((declaration) => {
 								const { init } = declaration;
 								if (
-									! init ||
+									!init ||
 									init.type !== 'CallExpression' ||
-									/** @type {import('estree').CallExpression} */ (
-										init
-									).callee.type !== 'Identifier' ||
-									/** @type {import('estree').Identifier} */ (
-										init.callee
-									).name !== 'require'
+									/** @type {import('estree').CallExpression} */ (init).callee
+										.type !== 'Identifier' ||
+									/** @type {import('estree').Identifier} */ (init.callee)
+										.name !== 'require'
 								) {
 									return;
 								}
@@ -211,51 +207,45 @@ module.exports = {
 								const { arguments: args } = init;
 								if (
 									args.length === 1 &&
-									args[ 0 ].type === 'Literal' &&
-									typeof args[ 0 ].value === 'string'
+									args[0].type === 'Literal' &&
+									typeof args[0].value === 'string'
 								) {
-									source = args[ 0 ].value;
-									candidates.push( [ child, source ] );
+									source = args[0].value;
+									candidates.push([child, source]);
 								}
-							} );
+							});
 					}
-				} );
+				});
 
-				for ( const [ child, source ] of candidates ) {
-					const locality = getPackageLocality( source );
-					if ( verified.has( locality ) ) {
+				for (const [child, source] of candidates) {
+					const locality = getPackageLocality(source);
+					if (verified.has(locality)) {
 						continue;
 					}
 
 					// Avoid verifying any other imports for the locality,
 					// regardless whether a correction must be made.
-					verified.add( locality );
+					verified.add(locality);
 
 					// Determine whether a correction must be made.
-					const correction = getDependencyBlockCorrection(
-						child,
-						locality,
-					);
-					if ( ! correction ) {
+					const correction = getDependencyBlockCorrection(child, locality);
+					if (!correction) {
 						continue;
 					}
 
-					context.report( {
+					context.report({
 						node: child,
-						message: `Expected preceding "${ locality } dependencies" comment block`,
-						fix( fixer ) {
+						message: `Expected preceding "${locality} dependencies" comment block`,
+						fix(fixer) {
 							const { comment, value } = correction;
-							const text = `/*${ value }*/`;
-							if ( comment && comment.range ) {
-								return fixer.replaceTextRange(
-									comment.range,
-									text,
-								);
+							const text = `/*${value}*/`;
+							if (comment && comment.range) {
+								return fixer.replaceTextRange(comment.range, text);
 							}
 
-							return fixer.insertTextBefore( child, text + '\n' );
+							return fixer.insertTextBefore(child, text + '\n');
 						},
-					} );
+					});
 				}
 			},
 		};

package/rules/index.js

@@ -2,8 +2,8 @@
  * Custom ESLint rules
  */
 module.exports = {
-	'dependency-group': require( './dependency-group' ),
-	'no-async-foreach': require( './no-async-foreach' ),
-	'no-unguarded-get-range-at': require( './no-unguarded-get-range-at' ),
-	'no-unused-vars-before-return': require( './no-unused-vars-before-return' ),
+	'dependency-group': require('./dependency-group'),
+	'no-async-foreach': require('./no-async-foreach'),
+	'no-unguarded-get-range-at': require('./no-unguarded-get-range-at'),
+	'no-unused-vars-before-return': require('./no-unused-vars-before-return'),
 };

package/rules/no-async-foreach.js

@@ -8,27 +8,25 @@
  */
 
 module.exports = {
-	create( context ) {
+	create(context) {
 		return {
-			ExpressionStatement( node ) {
+			ExpressionStatement(node) {
 				const { callee } = node.expression;
-				if ( ! callee || ! callee.property || ! callee.property.name ) {
+				if (!callee || !callee.property || !callee.property.name) {
 					return;
 				}
-				if ( callee.property.name === 'forEach' ) {
-					const functionArguments = node.expression.arguments.find(
-						( exp ) => {
-							return (
-								exp.type === 'ArrowFunctionExpression' ||
-								exp.type === 'FunctionExpression'
-							);
-						},
-					);
-					if ( functionArguments ) {
-						if ( functionArguments.async ) {
+				if (callee.property.name === 'forEach') {
+					const functionArguments = node.expression.arguments.find((exp) => {
+						return (
+							exp.type === 'ArrowFunctionExpression' ||
+							exp.type === 'FunctionExpression'
+						);
+					});
+					if (functionArguments) {
+						if (functionArguments.async) {
 							context.report(
 								node,
-								'Avoid passing an async function to Array.prototype.forEach',
+								'Avoid passing an async function to Array.prototype.forEach'
 							);
 						}
 					}

package/rules/no-unguarded-get-range-at.js

@@ -8,15 +8,15 @@ module.exports = {
 		type: 'problem',
 		schema: [],
 	},
-	create( context ) {
+	create(context) {
 		return {
 			'CallExpression[callee.object.callee.property.name="getSelection"][callee.property.name="getRangeAt"]'(
-				node,
+				node
 			) {
-				context.report( {
+				context.report({
 					node,
 					message: 'Avoid unguarded getRangeAt',
-				} );
+				});
 			},
 		};
 	},

package/rules/no-unused-vars-before-return.js

@@ -23,16 +23,16 @@ const FUNCTION_SCOPE_JSX_IDENTIFIERS = new WeakMap();
  *
  * @return {ESLintScope|undefined} Function scope, if known.
  */
-function getClosestFunctionScope( context ) {
+function getClosestFunctionScope(context) {
 	let functionScope = context.getScope();
-	while ( functionScope.type !== 'function' && functionScope.upper ) {
+	while (functionScope.type !== 'function' && functionScope.upper) {
 		functionScope = functionScope.upper;
 	}
 
 	return functionScope;
 }
 
-module.exports = /** @type {import('eslint').Rule} */ ( {
+module.exports = /** @type {import('eslint').Rule} */ ({
 	meta: {
 		type: 'problem',
 		schema: [
@@ -50,8 +50,8 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 	/**
 	 * @param {ESLintRuleContext} context Rule context.
 	 */
-	create( context ) {
-		const options = context.options[ 0 ] || {};
+	create(context) {
+		const options = context.options[0] || {};
 		const { excludePattern } = options;
 
 		/**
@@ -65,41 +65,35 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 		 *
 		 * @return {boolean} Whether declarator is emempt from consideration.
 		 */
-		function isExemptObjectDestructureDeclarator( node ) {
-			return (
-				node.id.type === 'ObjectPattern' &&
-				node.id.properties.length > 1
-			);
+		function isExemptObjectDestructureDeclarator(node) {
+			return node.id.type === 'ObjectPattern' && node.id.properties.length > 1;
 		}
 
 		return {
-			JSXIdentifier( node ) {
+			JSXIdentifier(node) {
 				// Currently, a scope's variable references does not include JSX
 				// identifiers. Account for this by visiting JSX identifiers
 				// first, and tracking them in a map per function scope, which
 				// is later merged with the known variable references.
-				const functionScope = getClosestFunctionScope( context );
-				if ( ! functionScope ) {
+				const functionScope = getClosestFunctionScope(context);
+				if (!functionScope) {
 					return;
 				}
 
-				if ( ! FUNCTION_SCOPE_JSX_IDENTIFIERS.has( functionScope ) ) {
-					FUNCTION_SCOPE_JSX_IDENTIFIERS.set(
-						functionScope,
-						new Set(),
-					);
+				if (!FUNCTION_SCOPE_JSX_IDENTIFIERS.has(functionScope)) {
+					FUNCTION_SCOPE_JSX_IDENTIFIERS.set(functionScope, new Set());
 				}
 
-				FUNCTION_SCOPE_JSX_IDENTIFIERS.get( functionScope ).add( node );
+				FUNCTION_SCOPE_JSX_IDENTIFIERS.get(functionScope).add(node);
 			},
-			'ReturnStatement:exit'( node ) {
-				const functionScope = getClosestFunctionScope( context );
-				if ( ! functionScope ) {
+			'ReturnStatement:exit'(node) {
+				const functionScope = getClosestFunctionScope(context);
+				if (!functionScope) {
 					return;
 				}
 
-				for ( const variable of functionScope.variables ) {
-					const declaratorCandidate = variable.defs.find( ( def ) => {
+				for (const variable of functionScope.variables) {
+					const declaratorCandidate = variable.defs.find((def) => {
 						return (
 							def.node.type === 'VariableDeclarator' &&
 							// Allow declarations which are not initialized.
@@ -107,21 +101,21 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 							// Target function calls as "expensive".
 							def.node.init.type === 'CallExpression' &&
 							// Allow unused if part of an object destructuring.
-							! isExemptObjectDestructureDeclarator( def.node ) &&
+							!isExemptObjectDestructureDeclarator(def.node) &&
 							// Only target assignments preceding `return`.
-							def.node.range[ 1 ] < node.range[ 1 ]
+							def.node.range[1] < node.range[1]
 						);
-					} );
+					});
 
-					if ( ! declaratorCandidate ) {
+					if (!declaratorCandidate) {
 						continue;
 					}
 
 					if (
 						excludePattern !== undefined &&
 						// eslint-disable-next-line security/detect-non-literal-regexp
-						new RegExp( excludePattern ).test(
-							declaratorCandidate.node.init.callee.name,
+						new RegExp(excludePattern).test(
+							declaratorCandidate.node.init.callee.name
 						)
 					) {
 						continue;
@@ -130,33 +124,32 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 					// The first entry in `references` is the declaration
 					// itself, which can be ignored.
 					const identifiers = variable.references
-						.slice( 1 )
-						.map( ( reference ) => reference.identifier );
+						.slice(1)
+						.map((reference) => reference.identifier);
 
 					// Merge with any JSX identifiers in scope, if any.
-					if ( FUNCTION_SCOPE_JSX_IDENTIFIERS.has( functionScope ) ) {
+					if (FUNCTION_SCOPE_JSX_IDENTIFIERS.has(functionScope)) {
 						const jsxIdentifiers =
-							FUNCTION_SCOPE_JSX_IDENTIFIERS.get( functionScope );
+							FUNCTION_SCOPE_JSX_IDENTIFIERS.get(functionScope);
 
-						identifiers.push( ...jsxIdentifiers );
+						identifiers.push(...jsxIdentifiers);
 					}
 
 					const isUsedBeforeReturn = identifiers.some(
-						( identifier ) =>
-							identifier.range[ 1 ] < node.range[ 1 ],
+						(identifier) => identifier.range[1] < node.range[1]
 					);
 
-					if ( isUsedBeforeReturn ) {
+					if (isUsedBeforeReturn) {
 						continue;
 					}
 
 					context.report(
 						declaratorCandidate.node,
 						'Variables should not be assigned until just prior its first reference. ' +
-							'An early return statement may leave this variable unused.',
+							'An early return statement may leave this variable unused.'
 					);
 				}
 			},
 		};
 	},
-} );
+});

package/utils/debug-log.js

@@ -0,0 +1,7 @@
+module.exports = function debugLog(message) {
+	if (process.env.DEBUG) {
+		// Debugging output.
+		// eslint-disable-next-line no-console
+		console.log(message);
+	}
+};

package/utils/is-package-installed.js

@@ -0,0 +1,34 @@
+const fs = require('node:fs');
+const debugLog = require('./debug-log');
+const findPackageJson = require('find-package-json');
+
+function findParent() {
+	const packages = [...findPackageJson()];
+	const firstPackage = packages.shift();
+
+	// A little hack to help us use this plugin to lint itself: When installed via
+	// NPM, .eslintrc.js will be missing (due to .npmignore).
+	if ('@automattic/eslint-plugin-wpvip' === firstPackage.name) {
+		const eslintRc = firstPackage.__path.replace(
+			/package\.json$/,
+			'.eslintrc.js'
+		);
+		// eslint-disable-next-line security/detect-non-literal-fs-filename
+		if (fs.statSync(eslintRc)) {
+			return firstPackage;
+		}
+	}
+
+	return packages.pop() || {};
+}
+
+const parent = findParent();
+
+debugLog(`Found package.json: ${parent.__path || 'none'}`);
+
+module.exports = function isPackageInstalled(packageName) {
+	const isDevDependency = !!parent.devDependencies?.[`${packageName}`];
+	const isProdDependency = !!parent.dependencies?.[`${packageName}`];
+
+	return isDevDependency || isProdDependency;
+};

package/.eslintignore

@@ -1,2 +0,0 @@
-__fixtures__/**/allowed.*
-__fixtures__/**/disallowed.*

package/.eslintrc.js

@@ -1,17 +0,0 @@
-/**
- * Do not copy this .eslintrc for your project. See the README for instructions.
- */
-
-module.exports = {
-	extends: [
-		'plugin:eslint-plugin/recommended', // linting for eslint plugins!
-		'plugin:@automattic/wpvip/base',
-		'plugin:@automattic/wpvip/formatting',
-		'plugin:@automattic/wpvip/testing',
-		'plugin:@automattic/wpvip/typescript',
-	],
-	parserOptions: {
-		project: './tsconfig.json',
-	},
-	root: true,
-};

package/.nvmrc

@@ -1 +0,0 @@
-16

package/configs/base.js

@@ -1,7 +0,0 @@
-module.exports = {
-	extends: [
-		'plugin:json/recommended',
-		'plugin:security/recommended',
-		require.resolve( './javascript' ),
-	],
-};

package/tsconfig.json

@@ -1,30 +0,0 @@
-{
-  "compilerOptions": {
-    // Allow JavaScript files as we migrate.
-    "allowJs": true,
-    "checkJs": false,
-
-    // https://www.typescriptlang.org/tsconfig#isolatedModules
-    "isolatedModules": true,
-
-    // Custom output directory (Nest default is ./dist).
-    "outDir": "./build",
-
-    // Preserve comments in output.
-    "removeComments": true,
-
-    // Allow importing JSON files directly.
-    "resolveJsonModule": true,
-
-    // The options below come from the default Nest tsconfig, minus those that
-    // are overridden above.
-    "allowSyntheticDefaultImports": true,
-    "baseUrl": ".",
-    "declaration": true,
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "incremental": true,
-    "sourceMap": true,
-    "strictNullChecks": true
-  }
-}