@automattic/eslint-plugin-wpvip 0.5.6 → 0.5.8

package/CONTRIBUTING.md

@@ -1,22 +1,9 @@
-# Contributing to `eslint-config-wpvip`
+# Contributing
 
 ## Getting Started
 
-Clone this repo and run `npm install`.
-
-The rules for this shared config are declared in [index.js](./index.js) and are automatically applied to the code in this repo.
+This repo provides custom ESLint rules (in `./rules`) and configs (`./configs`). Generally speaking, any change is welcome for discussion, but keep in mind that these rules and configs are used across all of our projects, so they need to be practical and flexible.
 
 ## Automated Testing
 
-We're using jest to confirm that our configuration does what we think it will.
-
-When you modify the rules, please add cases to the following files:
-
-* `__fixtures__/**/allowed.js` -- Syntax that should be allowed according to the rule(s) affected by your proposed change
-* `__fixtures__/**/disallowed.js` -- Syntax that should *NOT* be allowed according to the rule(s) affected by your proposed change
-
-After changing the rules or the `disallowed` fixture, run the following to update the snapshot of jest errors found:
-
-`npm run update-snapshot`
-
-...and commit the change to the snapshot file in your branch / PR.
+This repo lints itself! Try to add code in `__fixtures__` that will produce errors, confirm that the errors are caught, then run `npm run jest:update-snapshot` to expect the errors.

package/README.md

@@ -18,9 +18,7 @@ Create an `.eslintrc.js` file. **Note:** The `init` file allows you to avoid ins
 require( '@automattic/eslint-plugin-wpvip/init' );
 
 module.exports = {
-	extends: [
-		'plugin:@automattic/wpvip/recommended',
-	],
+	extends: [ 'plugin:@automattic/wpvip/recommended' ],
 	root: true,
 };
 ```
@@ -29,6 +27,24 @@ And that's it! It works automatically with most Babel and TypeScript projects. C
 
 You may also wish to define an `.eslintignore` file if there are files or paths that you do not want to lint.
 
+Package scripts can be useful to run linting and formatting commands automatically. Here are some suggested scripts for your project's `package.json`—only copy the ones that are useful to you. The `cmd:` scripts help you compose commands without repeating verbose CLI arguments.
+
+```json
+{
+	"scripts": {
+		"cmd:format": "prettier '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
+		"cmd:lint": "eslint --ext 'js,jsx,ts,tsx'",
+		"format": "npm run cmd:format -- --write",
+		"format:check": "npm run cmd:format -- --check",
+		"lint": "npm run cmd:lint .",
+		"lint:fix": "npm run cmd:lint . -- --fix",
+		"lint:ignore-warnings": "npm run cmd:lint . -- --quiet"
+	}
+}
+```
+
+**Note:** ESLint automatically ignores files listed in `.eslintignore` or you can target `.gitignore` using `--ignore-path`. Similarly, Prettier automatically ignores files listed in `.prettierignore` or you can target `.gitignore` using `--ignore-path`.
+
 ## Recommended config
 
 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.
@@ -41,9 +57,9 @@ module.exports = {
 		'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
+		'plugin:@automattic/wpvip/testing', // when "jest" is installed
+		'plugin:@automattic/wpvip/react', // when "react" is installed
+		'plugin:@automattic/wpvip/prettier', // when "prettier" is installed
 	],
 };
 ```
@@ -66,16 +82,17 @@ This repo also provides a Prettier config, which you can use with the following
 
 For maximum benefit, see [Prettier's documentation on enabling format-on-save in your editor](https://prettier.io/docs/en/editors.html). This enables you to concentrate on coding while Prettier handles formatting.
 
+### Editorconfig
+
+[Editorconfig](https://editorconfig.org/) provides additional formatting rules and works well with Prettier. Copy the [`.editorconfig` file](./.editorconfig) from this repo into your project.
+
 ## CLI
 
 The `cli` config allows certain behaviors that are usually against best practice but are useful in a codebase that produces a CLI tool:
 
 ```js
 module.exports = {
-	extends: [
-		'plugin:@automattic/wpvip/recommended',
-		'plugin:@automattic/wpvip/cli',
-	],
+	extends: [ 'plugin:@automattic/wpvip/recommended', 'plugin:@automattic/wpvip/cli' ],
 };
 ```
 
@@ -93,10 +110,7 @@ JSDoc is considered optional, especially compared to better alternatives like Ty
 
 ```js
 module.exports = {
-	extends: [
-		'plugin:@automattic/wpvip/recommended',
-		'plugin:@automattic/wpvip/jsdoc',
-	],
+	extends: [ 'plugin:@automattic/wpvip/recommended', 'plugin:@automattic/wpvip/jsdoc' ],
 };
 ```
 

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@automattic/eslint-plugin-wpvip",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "ESLint plugin for internal WordPress VIP projects",
   "main": "index.js",
   "scripts": {
     "check-types": "tsc __tests__/**/*.ts",
-    "format": "prettier --ignore-path .gitignore --ignore-path .prettierignore --write '**/*.{js,ts}'",
-    "jest": "npm run link-plugin && jest",
-    "jest:update-snapshot": "jest --updateSnapshot",
+    "cmd:format": "prettier --ignore-path .gitignore '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
+    "cmd:jest": "npm run link-plugin && jest",
+    "cmd:lint": "npm run link-plugin && eslint --ext 'js,jsx,ts,tsx'",
+    "format": "npm run cmd:format -- --write",
+    "format:check": "npm run cmd:format -- --check",
+    "jest": "npm run cmd:jest",
+    "jest:update-snapshot": "npm run cmd:jest -- --updateSnapshot",
     "link-plugin": "mkdir -p ./node_modules/@automattic; ln -fns $(pwd) ./node_modules/@automattic/eslint-plugin-wpvip",
-    "lint": "npm run link-plugin && eslint .",
+    "lint": "npm run cmd:lint .",
+    "lint:fix": "npm run cmd:lint . -- --fix",
     "test": "npm run jest"
   },
   "repository": {

package/prettierrc.js

@@ -1,11 +1,18 @@
 module.exports = {
 	arrowParens: 'avoid',
 	bracketSpacing: true,
-	jsxBracketSameLine: false,
 	parenSpacing: true,
 	printWidth: 100,
 	semi: true,
 	singleQuote: true,
 	trailingComma: 'es5',
 	useTabs: true,
+	overrides: [
+		{
+			files: [ '*.json', '*.yml', '*.yaml' ],
+			options: {
+				useTabs: false,
+			},
+		},
+	],
 };

package/rules/README.md

@@ -8,29 +8,29 @@ If you want to await a collection of tasks run in series (which is rarely the ca
 
 ```js
 async function* doTasks() {
-  let i = 0;
-  while (i < 10) {
-    yield i++;
-  }
+	let i = 0;
+	while ( i < 10 ) {
+		yield i++;
+	}
 }
 
-for await (const count of doTasks()) {
-	console.log(count);
+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. 
+`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'];
+const letters = [ 'a', 'b', 'c' ];
 
-letters.forEach(async letter => {
-  await processLetter(letter);
-});
+letters.forEach( async letter => {
+	await processLetter( letter );
+} );
 
-console.log('done! but not really');
+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/utils/is-package-installed.js

@@ -1,7 +1,23 @@
 const debugLog = require( './debug-log' );
 const findPackageJson = require( 'find-package-json' );
 
-const parent = findPackageJson( __dirname ).next()?.value || {};
+// Get a list of all package.json files in the current directory tree, ascending
+// up the tree from the current directory. Note that this code behaves differently
+// when it is installed as a package vs. when we are linting the code in this repo.
+//
+// When installed as a package, the current directory is inside node_modules and is
+// not the "package root" as we are thinking about it. In this case, we need to ignore
+// all package.json files that are inside node_modules directories.
+//
+// When we are linting the code in this repo, the current directory is not inside
+// node_modules and the first found "package.json" is the "package root."
+//
+// This problem is basically impossible to solve for all edge cases (like someone who
+// runs `npm run lint` from inside "node_modules") but this code should work for
+// most cases.
+const packages = [ ...findPackageJson( __dirname ) ];
+const parent =
+	packages.find( pkg => ! pkg.__path.includes( '/node_modules/' ) ) || packages.pop() || {};
 
 debugLog( `Found package.json: ${ parent.__path || 'none' }` );