@automattic/eslint-plugin-wpvip 0.5.7 → 0.6.0

package/CONTRIBUTING.md

@@ -1,22 +1,50 @@
-# 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.
+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.
+
+## Publishing a New Release
+
+The process to release to npm should be started when all pull requests intended for publishing have been merged and the software has been fully tested for publication. You can release either using GitHub Actions or locally.
+
+### Versioning Guidelines
+
+- `patch`: for non-breaking changes/bugfixes and small updates.
+- `minor`: for some new features, bug fixes, and other non-breaking changes.
+- `major`: for breaking changes.
+
+### Note on NPM token
+
+Publishing via the GitHub Action requires that the `NPM_TOKEN` be set correctly in GitHub Actions secrets. This should be an npm token generated for a bot user on [the npm @automattic org](https://www.npmjs.com/settings/automattic) that has publish access to this repo.
+
+### How To Release
+
+#### GitHub Actions (Preferred)
 
-When you modify the rules, please add cases to the following files:
+This is the preferred method for pushing out the latest release. The workflow runs a bunch of validations, generates a build, bump versions + tags, pushes out to npm, and bumps to the next dev version.
 
-* `__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
+1. Initiate the [release process here](https://github.com/Automattic/eslint-config-wpvip/actions/workflows/npm-prepare-release.yml).
+1. On the right-hand side, select "Run Workflow".
+1. Pick your preferred version bump.
+1. Click `Run Workflow`.
+1. Wait for a pull request to appear. The pull request will update the version number and shall be assigned to you.
+1. When ready, merge the pull request. This will lead to a new version to be [published on npmjs.com](https://www.npmjs.com/package/@automattic/eslint-plugin-wpvip).
+1. Another pull request will be created to bump to a development version, also assigned to you. Merge it to finish the process.
 
-After changing the rules or the `disallowed` fixture, run the following to update the snapshot of jest errors found:
+#### Local
 
-`npm run update-snapshot`
+If GitHub Actions is down or not working for some reason or you need to push a release for a previous version (e.g. security release), you can still publish a new release.
 
-...and commit the change to the snapshot file in your branch / PR.
+1. Check out the branch or commit you want to release using `git`.
+1. Run `npm run prepare` to generate the build.
+1. Create a new branch for the release: `git checkout -b release/vX.Y.Z` -- remember to update the version number in the branch name.
+1. Run`npm version <type>` to bump the version prior to publishing (see versioning types above).
+1. Commit the changes and create a pull request, then merge it in GitHub.
+1. Run`npm publish`.
+1. Create [a new release in Github](https://github.com/Automattic/eslint-config-wpvip/releases/new). Use the built-in "Generate Release Notes" to get release notes. Tag the version.
+1. Observe that the package has been released on GitHub and npmjs.com.

package/README.md

@@ -10,6 +10,10 @@ Install `eslint` and `@automattic/eslint-plugin-wpvip` to your project.
 npm install --save-dev eslint @automattic/eslint-plugin-wpvip
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/Automattic/eslint-config-wpvip/blob/trunk/CONTRIBUTING.md) for details on development, testing, publishing, etc.
+
 ## Configuration
 
 Create an `.eslintrc.js` file. **Note:** The `init` file allows you to avoid installing peer dependencies (available from `v0.5.0`).
@@ -18,9 +22,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 +31,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 +61,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 +86,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 +114,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/configs/javascript.js

@@ -24,7 +24,7 @@ module.exports = {
 	/**
 	 * Note: We must explicitly add this plugin to use our custom rules.
 	 */
-	plugins: [ '@automattic/wpvip', 'import', 'promise' ],
+	plugins: [ '@automattic/wpvip', 'import', 'promise', 'unused-imports' ],
 
 	/**
 	 * Please include a short description of the rule. For rules that downgrade or
@@ -132,6 +132,7 @@ module.exports = {
 		],
 
 		'import/no-unresolved': 'error',
+		'unused-imports/no-unused-imports': 'warn',
 
 		// Enforce Unix linebreaks. Included here and not in "formatting" since it
 		// is not controversial and helps with interchange.

package/configs/typescript.js

@@ -40,8 +40,8 @@ module.exports = {
 				// Use TypeScript-specific rules.
 				'no-duplicate-imports': 'off',
 				'no-shadow': 'off',
-				'@typescript-eslint/no-duplicate-imports': 'error',
 				'@typescript-eslint/no-shadow': 'error',
+				'import/no-duplicates': 'error',
 
 				// Handled by TS itself.
 				'no-unused-vars': 'off',

package/configs/weak-typescript.js

@@ -37,6 +37,8 @@ module.exports = {
 				'@typescript-eslint/restrict-template-expressions': 'warn',
 
 				'@typescript-eslint/unbound-method': 'warn',
+
+				'import/no-duplicates': 'warn',
 			},
 		},
 	],

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@automattic/eslint-plugin-wpvip",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "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",
+    "check-types": "tsc -p tsconfig.check.json",
+    "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": {
@@ -27,14 +32,14 @@
   },
   "homepage": "https://github.com/Automattic/eslint-config-wpvip#readme",
   "dependencies": {
-    "@babel/eslint-parser": "7.21.3",
-    "@rushstack/eslint-patch": "1.2.0",
-    "@typescript-eslint/eslint-plugin": "5.55.0",
-    "@typescript-eslint/parser": "5.55.0",
+    "@babel/eslint-parser": "7.22.10",
+    "@rushstack/eslint-patch": "1.3.3",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
     "eslint-config-prettier": "8.7.0",
     "eslint-import-resolver-typescript": "3.5.3",
-    "eslint-plugin-import": "2.27.5",
-    "eslint-plugin-jest": "27.2.1",
+    "eslint-plugin-import": "2.28.1",
+    "eslint-plugin-jest": "27.2.3",
     "eslint-plugin-jsdoc": "40.0.2",
     "eslint-plugin-json": "3.1.0",
     "eslint-plugin-jsx-a11y": "6.7.1",
@@ -43,6 +48,7 @@
     "eslint-plugin-react": "7.32.2",
     "eslint-plugin-react-hooks": "4.6.0",
     "eslint-plugin-security": "1.7.1",
+    "eslint-plugin-unused-imports": "3.0.0",
     "find-package-json": "1.2.0",
     "globals": "13.20.0"
   },
@@ -51,9 +57,9 @@
   },
   "devDependencies": {
     "@tsconfig/node18": "1.0.1",
-    "@types/eslint": "8.37.0",
+    "@types/eslint": "8.44.2",
     "@types/jest": "29.5.0",
-    "eslint": "8.35.0",
+    "eslint": "8.47.0",
     "jest": "29.5.0",
     "prettier": "npm:wp-prettier@2.8.5",
     "ts-jest": "29.0.5",

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/tsconfig.check.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [ "__fixtures__" ]
+}