@automattic/eslint-plugin-wpvip 1.2.0 → 1.3.0

package/README.md

@@ -10,13 +10,15 @@ Install `eslint` and `@automattic/eslint-plugin-wpvip` to your project.
 npm install --save-dev eslint @automattic/eslint-plugin-wpvip
 ```
 
+Optional integrations are auto-detected when your project also installs `typescript`, `jest`, `react`, or `prettier`. These packages are declared as optional peer dependencies so consumers can opt in to the stacks they actually use.
+
 ## 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`).
+Create an `.eslintrc.js` file. If you use the `recommended` preset, you can preload the optional integrations with `init`.
 
 ```js
 require( '@automattic/eslint-plugin-wpvip/init' );
@@ -29,6 +31,8 @@ module.exports = {
 
 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.
 
+If your project uses only JavaScript, you do not need to install the optional peers. If you use the modular `typescript`, `testing`, `react`, or `prettier` configs directly, install the corresponding package in your project first.
+
 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.
@@ -59,8 +63,8 @@ Of course, this recommended config may not be ideal for every project, so feel f
 module.exports = {
 	extends: [
 		'plugin:@automattic/wpvip/javascript',
-		'plugin:@automattic/wpvip/typescript', // when "typescript" is installed
 		'plugin:@automattic/wpvip/formatting',
+		'plugin:@automattic/wpvip/typescript', // when "typescript" 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

package/configs/index.js

@@ -5,14 +5,41 @@ const configs = {
 	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' ),
 };
 
+// Optional configs are lazy-loaded to avoid MODULE_NOT_FOUND crashes when
+// optional peers (typescript, react, jest, prettier) are not installed.
+// These are only accessed when explicitly requested (e.g., via direct extends)
+// or via recommended config, which guards their loading via loadOptionalConfig.
+const optionalConfigs = [ 'prettier', 'react', 'testing', 'typescript' ];
+
+function requireOptionalConfig( name ) {
+	switch ( name ) {
+		case 'prettier':
+			return require( './prettier' );
+		case 'react':
+			return require( './react' );
+		case 'testing':
+			return require( './testing' );
+		case 'typescript':
+			return require( './typescript' );
+		default:
+			throw new Error( `Unknown optional config: ${ name }` );
+	}
+}
+
+for ( const name of optionalConfigs ) {
+	Object.defineProperty( configs, name, {
+		enumerable: true,
+		configurable: true,
+		get() {
+			return requireOptionalConfig( name );
+		},
+	} );
+}
+
 module.exports = configs;

package/configs/javascript.js

@@ -14,6 +14,15 @@ const SecurityPluginConfigs = require( 'eslint-plugin-security' );
 const UnusedImportsPlugin = require( 'eslint-plugin-unused-imports' );
 const globals = require( 'globals' );
 
+// Resolve the TypeScript resolver from this package's perspective so that
+// eslint-plugin-import can load it regardless of how the consuming project
+// hoists its dependencies. Passing the absolute path as the resolver name
+// bypasses `eslint-plugin-import`'s name-based lookup, which otherwise tries
+// to resolve `eslint-import-resolver-typescript` from each linted source
+// file's path and silently falls back to requiring `typescript` (the
+// compiler) when the resolver is nested under this plugin's node_modules.
+const typescriptResolverPath = require.resolve( 'eslint-import-resolver-typescript' );
+
 /** @type import('eslint').Linter.Config[] */
 module.exports = [
 	JsonPlugin.configs.recommended,
@@ -273,8 +282,10 @@ module.exports = [
 				node: {
 					extensions: [ '.js', '.jsx', '.ts', '.tsx', '.cjs', '.mjs', '.cts', '.mts' ],
 				},
-				typescript: 'eslint-import-resolver-typescript',
+				[ typescriptResolverPath ]: {},
 			},
 		},
 	},
 ];
+
+module.exports.typescriptResolverPath = typescriptResolverPath;

package/configs/recommended.js

@@ -1,22 +1,13 @@
-const isPackageInstalled = require( '../utils/is-package-installed' );
+const loadOptionalConfig = require( '../utils/load-optional-config' );
 
 /** @type import('eslint').Linter.Config[] */
 const configs = [ ...require( './javascript' ), ...require( './formatting' ) ];
 
-if ( isPackageInstalled( 'typescript' ) ) {
-	configs.push( ...require( './typescript' ) );
-}
+configs.push( ...loadOptionalConfig( 'typescript', () => require( './typescript' ) ) );
+configs.push( ...loadOptionalConfig( 'jest', () => require( './testing' ) ) );
+configs.push( ...loadOptionalConfig( 'react', () => require( './react' ) ) );
+configs.push( ...loadOptionalConfig( 'prettier', () => require( './prettier' ) ) );
 
-if ( isPackageInstalled( 'jest' ) ) {
-	configs.push( ...require( './testing' ) );
-}
-
-if ( isPackageInstalled( 'react' ) ) {
-	configs.push( ...require( './react' ) );
-}
-
-if ( isPackageInstalled( 'prettier' ) ) {
-	configs.push( ...require( './prettier' ) );
-}
+configs.typescriptResolverPath = require( './javascript' ).typescriptResolverPath;
 
 module.exports = configs;

package/configs/weak-typescript.js

@@ -16,14 +16,47 @@ module.exports = [
 		 * to "off"). If a rule is already set to a warning, do not disable it.
 		 */
 		rules: {
+			'@typescript-eslint/await-thenable': 'warn',
+			'@typescript-eslint/ban-ts-comment': 'warn',
+			'@typescript-eslint/default-param-last': 'warn',
+			'@typescript-eslint/explicit-member-accessibility': [
+				'warn',
+				{ overrides: { constructors: 'off' } },
+			],
+			'@typescript-eslint/no-base-to-string': 'warn',
+			'@typescript-eslint/no-duplicate-type-constituents': 'warn',
+			'@typescript-eslint/no-dynamic-delete': 'warn',
+			'@typescript-eslint/no-empty-object-type': 'warn',
 			'@typescript-eslint/no-explicit-any': 'warn',
 			'@typescript-eslint/no-floating-promises': 'warn',
+			'@typescript-eslint/no-namespace': 'warn',
+			'@typescript-eslint/no-non-null-assertion': 'warn',
 			'@typescript-eslint/no-misused-promises': 'warn',
+			'@typescript-eslint/no-invalid-void-type': [ 'warn', { allowAsThisParameter: true } ],
+			'@typescript-eslint/no-redundant-type-constituents': 'warn',
+			'@typescript-eslint/no-require-imports': 'warn',
+			'@typescript-eslint/no-this-alias': 'warn',
 			'@typescript-eslint/no-unsafe-argument': 'warn',
 			'@typescript-eslint/no-unsafe-assignment': 'warn',
 			'@typescript-eslint/no-unsafe-call': 'warn',
+			'@typescript-eslint/no-unsafe-enum-comparison': 'warn',
+			'@typescript-eslint/no-unsafe-function-type': 'warn',
 			'@typescript-eslint/no-unsafe-member-access': 'warn',
 			'@typescript-eslint/no-unsafe-return': 'warn',
+			'no-unused-vars': 'off',
+			'@typescript-eslint/no-unused-vars': [
+				'warn',
+				{
+					argsIgnorePattern: '^_',
+					caughtErrorsIgnorePattern: '^_',
+					destructuredArrayIgnorePattern: '^_',
+					ignoreRestSiblings: true,
+					varsIgnorePattern: '^_',
+				},
+			],
+			'@typescript-eslint/no-wrapper-object-types': 'warn',
+			'@typescript-eslint/only-throw-error': 'warn',
+			'@typescript-eslint/prefer-promise-reject-errors': 'warn',
 			'@typescript-eslint/require-await': 'warn',
 			'@typescript-eslint/restrict-plus-operands': 'warn',
 			'@typescript-eslint/restrict-template-expressions': 'warn',

package/index.js

@@ -2,5 +2,6 @@ const configs = require( './configs' );
 const plugin = require( './plugin' );
 
 plugin.configs = configs;
+plugin.typescriptResolverPath = require( './configs/javascript' ).typescriptResolverPath;
 
 module.exports = plugin;

package/init.js

@@ -0,0 +1,6 @@
+const loadOptionalConfig = require( './utils/load-optional-config' );
+
+loadOptionalConfig( 'typescript', () => require( './configs/typescript' ) );
+loadOptionalConfig( 'jest', () => require( './configs/testing' ) );
+loadOptionalConfig( 'react', () => require( './configs/react' ) );
+loadOptionalConfig( 'prettier', () => require( './configs/prettier' ) );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/eslint-plugin-wpvip",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "ESLint plugin for internal WordPress VIP projects",
   "main": "index.js",
   "scripts": {
@@ -38,32 +38,50 @@
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jest": "^29.12.2",
-    "eslint-plugin-jsdoc": "^62.5.4",
+    "eslint-plugin-jsdoc": "^63.0.0",
     "eslint-plugin-json": "^4.0.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-security": "^3.0.1",
+    "eslint-plugin-security": "^4.0.0",
     "eslint-plugin-unused-imports": "^4.3.0",
     "find-package-json": "^1.2.0",
     "globals": "^16.0.0 || ^17.0.0",
     "typescript-eslint": "^8.48.1"
   },
   "peerDependencies": {
-    "eslint": "^9.7.0"
+    "eslint": "^9.7.0",
+    "jest": "^29.0.0 || ^30.0.0",
+    "prettier": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0 || ^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jest": {
+      "optional": true
+    },
+    "prettier": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@tsconfig/node20": "^20.1.8",
-    "@types/eslint": "9.6.1",
-    "@types/jest": "30.0.0",
-    "@types/react": "19.2.7",
+    "@types/eslint": "^9.6.1",
+    "@types/jest": "^30.0.0",
+    "@types/react": "~19.2.7",
     "eslint": "^9.39.1",
-    "jest": "30.2.0",
+    "jest": "^30.4.2",
     "prettier": "npm:wp-prettier@3.0.3",
-    "react": "19.2.3",
-    "ts-jest": "29.4.6",
-    "typescript": "5.9.3"
+    "react": "~19.2.3",
+    "ts-jest": "^29.4.6",
+    "typescript": "^6.0.3"
   }
 }

package/utils/load-optional-config.js

@@ -0,0 +1,30 @@
+const debugLog = require( './debug-log' );
+const isPackageInstalled = require( './is-package-installed' );
+
+module.exports = function loadOptionalConfig( packageName, loadConfig ) {
+	if ( ! isPackageInstalled( packageName ) ) {
+		return [];
+	}
+
+	try {
+		return loadConfig();
+	} catch ( error ) {
+		if ( 'MODULE_NOT_FOUND' !== error?.code ) {
+			throw error;
+		}
+
+		// Only swallow the error if the missing module is the optional peer itself.
+		// This prevents masking errors from transitive dependencies or unrelated modules.
+		const missingModule = error.message?.match( /Cannot find module '([^']+)'/ )?.[ 1 ] || '';
+		const isOptionalPeerMissing =
+			missingModule === packageName || missingModule.startsWith( `${ packageName }/` );
+
+		if ( ! isOptionalPeerMissing ) {
+			throw error;
+		}
+
+		debugLog( `Skipping optional config for ${ packageName }: ${ error.message }` );
+
+		return [];
+	}
+};