@automattic/eslint-plugin-wpvip 0.4.3 → 0.4.5

package/.eslintignore

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

package/.eslintrc.js

@@ -0,0 +1,14 @@
+/**
+ * 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',
+	],
+	parserOptions: {
+		project: './tsconfig.json',
+	},
+	root: true,
+};

package/README.md

@@ -10,93 +10,108 @@ Install `eslint` and `@automattic/eslint-plugin-wpvip` to your project.
 npm install --save-dev eslint @automattic/eslint-plugin-wpvip
 ```
 
-If your project uses TypeScript, make sure `typescript` is installed as well.
-
 ## Configuration
 
-Create an `.eslintrc.js` file with your desired presets. Note: The first line `require`s an init helper that allows you to avoid installing peer dependencies (available from `v0.5.0`).
-
-Here is an example that would suit a project that uses React and TypeScript and has Jest unit tests:
+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`).
 
-```
+```js
 require( '@automattic/eslint-plugin-wpvip/init' );
 
 module.exports = {
 	extends: [
 		'plugin:@automattic/wpvip/base',
-		'plugin:@automattic/wpvip/react',
-		'plugin:@automattic/wpvip/testing',
-		'plugin:@automattic/wpvip/typescript',
 	]
 }
 ```
 
-And that's it! Code editors that are configured to work with ESLint will automatically pick up the rulesets and flag any errors or warnings.
+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: setup a `lint` npm script in `package.json`:
+Tip: Set up a `lint` npm script in `package.json`:
 
-```
+```json
 "scripts": {
-  "lint": "eslint .",
-  "test": "npm run lint"
+  "lint": "eslint ."
 }
 ```
 
-## Available presets
+You may also wish to define an `.eslintignore` file if there are files or paths that you do not want to lint.
 
-Use these presets in the `extends` section of your `eslintrc`:
+## TypeScript
 
-- `plugin:@automattic/wpvip/base`
-- `plugin:@automattic/wpvip/prettier`
-- `plugin:@automattic/wpvip/react`
-- `plugin:@automattic/wpvip/testing`
-- `plugin:@automattic/wpvip/typescript`
-- `plugin:@automattic/wpvip/typescript-migration`
-- `plugin:@automattic/wpvip/typescript-strict`
+TypeScript rules are automatically added whenever your project has installed the [`typescript` NPM package]() as a dependency.
 
 ## Prettier
 
-This plugin comes with support for `prettier`. Configure it by [adding a `.prettierrc`](https://prettier.io/docs/en/configuration.html) to your project and enabling the `@automattic/wpvip/prettier` preset:
+Prettier integration with ESLint is automatically enabled whenever your project has installed the [`prettier` NPM package](https://www.npmjs.com/package/prettier) as a dependency.
 
+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:
+
+```json
+{
+  "useTabs": false
+}
 ```
+
+If you have installed the `prettier` NPM package but wish to disable the automatic integration, add the `prettier-off` config to your `.eslintrc.js`:
+
+```json
 {
 	"extends": [
 		"plugin:@automattic/wpvip/base",
-		"plugin:@automattic/wpvip/prettier"
+		"plugin:@automattic/wpvip/prettier-off"
 	]
 }
 ```
 
-## Migrating
+## CLI
 
-Changing linter rules can be tricky and lead to huge PRs. To ease adoption, we can add [eslines](https://github.com/Automattic/eslines) to our project, to turn lint errors into warnings.
+The `cli` config allows certain behaviors that are usually against best practice but are useful in a codebase that produces a CLI tool:
 
-```sh
-npm i --save-dev eslines
+```json
+{
+	"extends": [
+		"plugin:@automattic/wpvip/base",
+		"plugin:@automattic/wpvip/cli"
+	]
+}
 ```
 
-Add the default `.eslines.json` to your project root:
+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.
+
+## 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:
+
+```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) {}
 ```
+
+If you want to enforce the use of JSDoc, use the `jsdoc` config:
+
+```json
 {
-    "branches": {
-        "default": ["downgrade-unmodified-lines"]
-    },
-    "processors": {
-        "downgrade-unmodified-lines": {
-            "remote": "origin/master",
-            "rulesNotToDowngrade": ["no-unused-vars"]
-        }
-    }
+	"extends": [
+		"plugin:@automattic/wpvip/base",
+		"plugin:@automattic/wpvip/jsdoc"
+	]
 }
 ```
 
-Then modify the `npm run lint` command to pass through to `eslines`:
+## "Weak" configs
 
-```
-"scripts": {
-  "lint": "eslint -f json . | eslines"
-}
-```
+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.
+
+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.
 
-Errors will still appear in any code editor that supports ESLint, but tests will continue to pass as the code is migrated to the new rulesets.
+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.

package/configs/base.js

@@ -1,27 +1,27 @@
-module.exports = {
+const isPackageInstalled = require('@wordpress/eslint-plugin/utils/is-package-installed');
+
+const baseConfig = {
 	env: {
 		node: true,
 	},
 	extends: [
-		'plugin:@wordpress/eslint-plugin/recommended-with-formatting',
 		'eslint:recommended',
+		'plugin:@wordpress/eslint-plugin/recommended',
 		'plugin:json/recommended',
 		'plugin:security/recommended',
 	],
-	plugins: [
-		'no-async-foreach',
-	],
+	/**
+	 * We must explicitly add this plugin to use our custom rules.
+	 */
+	plugins: ['@automattic/wpvip'],
 	/**
 	 * Please include a short description of the rule. For rules that downgrade or
 	 * disable errors, include a brief justification or reasoning.
 	 */
 	rules: {
-		// Parenthesis should be omitted for arrow functions when there is a single
-		// argument.
-		'arrow-parens': [
-			'warn',
-			'as-needed',
-		],
+		// Async/await must not be used in a `.forEach` method, because the result
+		// will not be awaited in the outer scope.
+		'@automattic/wpvip/no-async-foreach': 'error',
 
 		// Identifiers should be in camelCase. Object properties are excluded
 		// (including when destructuring) since they often come from external
@@ -38,7 +38,7 @@ module.exports = {
 		complexity: 'error',
 
 		// Files must end in a newline.
-		'eol-last': [ 'error', 'always' ],
+		'eol-last': ['error', 'always'],
 
 		// Identifiers should be between 2 and 40 characters in length.
 		'id-length': [
@@ -49,6 +49,14 @@ module.exports = {
 			},
 		],
 
+		// Disable JSDoc rule to require param definitions. While other JSDoc rules
+		// are still present and active, they are effectively dormant unless
+		// triggered by invalid or insufficient JSDoc. In other words, if you don't
+		// attempt JSDoc, none will be required by the linter.
+		//
+		// Reenable this rule with the jsdoc preset.
+		'jsdoc/require-param': 'off',
+
 		// Lines containing code should be a maximum of 200 characters in length.
 		'max-len': [
 			'warn',
@@ -57,10 +65,6 @@ module.exports = {
 			},
 		],
 
-		// Async/await must not be used in a `.forEach` method, because the result
-		// will not be awaited in the outer scope.
-		'no-async-foreach/no-async-foreach': 'error',
-
 		// Async/await must not be used in a loop, because it leads to sequential
 		// execution, when parallel execution is almost always preferred.
 		'no-await-in-loop': 'error',
@@ -89,15 +93,6 @@ module.exports = {
 		// `parseInt` calls must always supply a radix argument.
 		radix: 'error',
 
-		// Parentheses must include ( spaces ), except when empty.
-		'space-in-parens': [
-			'error',
-			'always',
-			{
-				exceptions: [ 'empty' ],
-			},
-		],
-
 		// Comments should always include consistent spacing for readability.
 		'spaced-comment': 'warn',
 
@@ -109,4 +104,35 @@ module.exports = {
 			},
 		],
 	},
+	overrides: [],
 };
+
+// Make our default TypeScript rules more useful.
+if (isPackageInstalled('typescript')) {
+	baseConfig.overrides.push({
+		extends: [
+			'plugin:@typescript-eslint/recommended-requiring-type-checking',
+			'plugin:@typescript-eslint/strict',
+		],
+		files: ['**/*.ts', '**/*.tsx'],
+		rules: {
+			// TypeScript `any` type must not be used. This is a warning in the base
+			// config, and is elevated to an error here.
+			'@typescript-eslint/no-explicit-any': 'error',
+		},
+	});
+}
+
+// Make our default React rules more useful.
+if (isPackageInstalled('react')) {
+	// @TODO
+}
+
+// Add Jest-specific rules if it is installed.
+if (isPackageInstalled('jest')) {
+	baseConfig.env['jest/globals'] = true;
+	baseConfig.extends.push('plugin:jest/recommended');
+	baseConfig.plugins.push('jest');
+}
+
+module.exports = baseConfig;

package/configs/index.js

@@ -1,10 +1,8 @@
 module.exports = {
-	base: require( './base' ),
-	cli: require( './cli' ),
-	prettier: require( './prettier' ),
-	react: require( './react' ),
-	testing: require( './testing' ),
-	typescript: require( './typescript' ),
-	'typescript/migration': require( './typescript-migration' ),
-	'typescript/strict': require( './typescript-strict' ),
+	base: require('./base'),
+	cli: require('./cli'),
+	jsdoc: require('./jsdoc'),
+	'prettier-off': require('./prettier-off'),
+	weak: require('./weak'),
+	'weak-typescript': require('./weak-typescript'),
 };

package/configs/jsdoc.js

@@ -0,0 +1,12 @@
+module.exports = {
+	/**
+	 * Please include a short description of the rule. For rules that downgrade or
+	 * disable errors, include a brief justification or reasoning.
+	 */
+	rules: {
+		// Reenable the requirement to document function parameters, which in turn
+		// enables additional lint rules to ensure accuracy and proper formatting.
+		// This overrides the base preset.
+		'jsdoc/require-param': 'error',
+	},
+};

package/configs/{react.js → prettier-off.js}

@@ -3,5 +3,7 @@ module.exports = {
 	 * Please include a short description of the rule. For rules that downgrade or
 	 * disable errors, include a brief justification or reasoning.
 	 */
-	rules: {},
+	rules: {
+		'prettier/prettier': 'off',
+	},
 };

package/configs/weak-typescript.js

@@ -0,0 +1,18 @@
+/**
+ * "Weak" TypeScript rules
+ * ==========================
+ * These rules are intended to extend the base `typescript` rules and will help
+ * you migrate an existing project to TypeScript.
+ */
+module.exports = {
+	/**
+	 * Downgrade rules from the base preset to "warning". Do not disable
+	 * rules (set to "off"). If a rule is already set to a warning, do not
+	 * disable it.
+	 *
+	 * An example is the `@typescript-eslint/no-explicit-any` rule, which is set
+	 * to `warning` in the base preset (via `@typescript-eslint/recommended`) and
+	 * is intentionally not overridden here.
+	 */
+	rules: {},
+};

package/configs/weak.js

@@ -0,0 +1,16 @@
+/**
+ * "Weak" rules
+ * ============
+ * These rules are intended for codebases that are transitioning to the stronger
+ * base preset but need weaker rules to prevent a massive number of changes.
+ * They do not provide good protection or standardization, but can useful on a
+ * temporary basis.
+ */
+module.exports = {
+	/**
+	 * Downgrade rules from the base preset to "warning". 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,13 +1,14 @@
 {
   "name": "@automattic/eslint-plugin-wpvip",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "ESLint plugin for internal WordPress VIP projects",
   "main": "index.js",
   "scripts": {
     "jest": "jest",
     "jest:update-snapshot": "jest --updateSnapshot",
-    "lint": "eslint --ignore-pattern '__fixtures__' .",
-    "test": "npm run lint && jest"
+    "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"
   },
   "repository": {
     "type": "git",
@@ -28,7 +29,6 @@
     "@wordpress/eslint-plugin": "13.10.0",
     "eslint-plugin-jest": "27.2.1",
     "eslint-plugin-json": "3.1.0",
-    "eslint-plugin-no-async-foreach": "0.1.1",
     "eslint-plugin-security": "1.7.1"
   },
   "peerDependencies": {
@@ -36,6 +36,7 @@
   },
   "devDependencies": {
     "eslint": "8.35.0",
+    "eslint-plugin-eslint-plugin": "5.0.8",
     "jest": "29.5.0",
     "prettier": "2.8.4",
     "typescript": "4.9.5"

package/rules/README.md

@@ -0,0 +1,36 @@
+# Custom rules
+
+## `no-async-foreach`
+
+**tl;dr:** Do not use `Array.prototype.forEach` with async/await. If you want to await a collection of tasks run in parallel, use `await Promise.all()` and `Array.prototype.map`.
+
+If you want to await a collection of tasks run in series (which is rarely the case), then either `await` them individually without using an array or use a generator and `for await ... of`:
+
+```js
+async function* doTasks() {
+  let i = 0;
+  while (i < 10) {
+    yield i++;
+  }
+}
+
+for await (const count of doTasks()) {
+	console.log(count);
+}
+```
+
+### The problem
+
+`Array.prototype.forEach` is not designed for async/await/promises. Even if the function passed to `.forEach` is `async`, each iteration does not `await` the result. 
+
+```js
+const letters = ['a', 'b', 'c'];
+
+letters.forEach(async letter => {
+  await processLetter(letter);
+});
+
+console.log('done! but not really');
+```
+
+In the example above, `'done! but not really'` is logged before the promises returned by `processLetter` have resolved. This is because the array is iterated immediately and execution proceeds without awaiting promise resolution.

package/rules/index.js

@@ -1,5 +1,4 @@
 module.exports = {
-	rules: {
-		// Custom ESLint rules
-	},
+	// Custom ESLint rules
+	'no-async-foreach': require('./no-async-foreach'),
 };

package/rules/no-async-foreach.js

@@ -0,0 +1,38 @@
+/**
+ * Rule: @automattic/wpvip/no-async-foreach
+ *
+ *
+ *
+ * Adapted from unmaintained eslint plugin:
+ * https://www.npmjs.com/package/eslint-plugin-no-async-foreach
+ */
+
+module.exports = {
+	create(context) {
+		return {
+			ExpressionStatement(node) {
+				const { callee } = node.expression;
+				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) {
+							context.report(
+								node,
+								'Avoid passing an async function to Array.prototype.forEach'
+							);
+						}
+					}
+				}
+			},
+		};
+	},
+};

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "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
+  }
+}

package/.eslintrc.json

@@ -1,14 +0,0 @@
-{
-	"plugins": [
-		"jest"
-	],
-	"env": {
-		"jest/globals": true
-	},
-	"extends": [
-		"./configs/base",
-		"./configs/cli",
-		"./configs/testing",
-		"./rules"
-	]
-}

package/configs/prettier.js

@@ -1,13 +0,0 @@
-module.exports = {
-	extends: [
-		'plugin:prettier/recommended',
-	],
-	/**
-	 * Please include a short description of the rule. For rules that downgrade or
-	 * disable errors, include a brief justification or reasoning.
-	 */
-	rules: {
-		// Raise Prettier errors as ESLint errors.
-		'prettier/prettier': 'error',
-	},
-};

package/configs/testing.js

@@ -1,7 +0,0 @@
-module.exports = {
-	/**
-	 * Please include a short description of the rule. For rules that downgrade or
-	 * disable errors, include a brief justification or reasoning.
-	 */
-	rules: {},
-};

package/configs/typescript-migration.js

@@ -1,23 +0,0 @@
-/**
- * TypeScript migration rules
- * ==========================
- * These rules are intended to extend the base `typescript` rules and will help
- * you migrate an existing project to TypeScript.
- */
-module.exports = {
-	/**
-	 * Please include a short description of the rule. For rules that downgrade or
-	 * disable errors, include a brief justification or reasoning.
-	 *
-	 * NOTE: Before disabling a rule, first consider keeping it and/or downgrading
-	 * it to a warning. This allows the rule to surface helpful advice in your
-	 * editor and nudge you towards best practices, but will not fail your lint
-	 * step while you work to migrate your codebase.
-	 *
-	 * An example is the `@typescript-eslint/no-explicit-any` rule, which is set
-	 * to `warning` in the `@typescript-eslint/recommended` preset and is
-	 * intentionally not overridden here.
-	 */
-	rules: {},
-};
-

package/configs/typescript-strict.js

@@ -1,20 +0,0 @@
-/**
- * TypeScript strict rules
- * =======================
- * These rules are intended to extend the base `typescript` rules and will help
- * you enforce additional best practices for TypeScript projects.
- */
-module.exports = {
-	extends: [
-		'plugin:@typescript-eslint/recommended-requiring-type-checking',
-	],
-	/**
-	 * Please include a short description of the rule. For rules that downgrade or
-	 * disable errors, include a brief justification or reasoning.
-	 */
-	rules: {
-		// TypeScript `any` type must not be used. This is a warning in the base
-		// config, and is elevated to an error here.
-		'@typescript-eslint/no-explicit-any': 'error',
-	},
-};

package/configs/typescript.js

@@ -1,62 +0,0 @@
-/**
- * Base TypeScript rules
- * =====================
- * These rules are intended to be used for all VIP TypeScript projects. They can
- * be extended by `typescript-migration` (to make migration to TypeScript
- * easier) and `typescript-strict` (to enforce additional best practices).
- *
- * Note that, if you also use the `@wordpress/eslint-plugin/recommended` preset,
- * a number of TypeScript rules are automattically added whenever TypeScript is
- * installed as a dependency of your project:
- *
- * https://github.com/WordPress/gutenberg/blob/trunk/packages/eslint-plugin/configs/recommended.js
- */
-module.exports = {
-	extends: [
-		'plugin:@typescript-eslint/recommended',
-	],
-	/**
-	 * Please include a short description of the rule. For rules that downgrade or
-	 * disable errors, include a brief justification or reasoning.
-	 */
-	ignorePatterns: [ '**/*.d.ts' ],
-	overrides: [
-		{
-			files: [ '**/*.ts', '**/*.tsx' ],
-			parser: '@typescript-eslint/parser',
-			// Note that these rules only take effect in TypeScript files (.ts, .tsx).
-			rules: {
-				// Prefer the TypeScript versions of some rules.
-				'no-duplicate-imports': 'off',
-				'@typescript-eslint/no-duplicate-imports': 'error',
-				'no-shadow': 'off',
-				'@typescript-eslint/no-shadow': 'error',
-
-				// Don't require redundant JSDoc parameter descriptions and types in
-				// TypeScript files.
-				'jsdoc/require-param': 'off',
-				'jsdoc/require-param-type': 'off',
-				'jsdoc/require-returns-type': 'off',
-			},
-		},
-	],
-	plugins: [ '@typescript-eslint' ],
-	rules: {
-		// Elevate the unused vars rule to an error, but allow it to be suppressed
-		// with a naming convention.
-		'@typescript-eslint/no-unused-vars': [
-			'error',
-			{
-				// Allow unused vars if they are prefixed with "_".
-				argsIgnorePattern: '^_',
-			},
-		],
-	},
-	settings: {
-		'import/resolver': {
-			node: {
-				extensions: [ '.js', '.jsx', '.ts', '.tsx' ],
-			},
-		},
-	},
-};