eslint-docgen 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-docgen",
-	"version": "0.8.0",
+	"version": "0.8.1",
 	"description": "Automatically generate ESLint plugin documentation from rule metadata and test cases.",
 	"repository": {
 		"type": "git",
@@ -19,8 +19,8 @@
 		"src"
 	],
 	"scripts": {
-		"test": "eslint . --cache && nyc mocha tests/",
-		"report": "nyc report --reporter=html"
+		"test": "eslint . --cache && c8 mocha tests/",
+		"report": "c8 report --reporter=html"
 	},
 	"engines": {
 		"node": ">=20.0.0"
@@ -28,7 +28,6 @@
 	"dependencies": {
 		"chalk": "^4.1.2",
 		"ejs": "^4.0.1",
-		"eslint": ">=8.0.0",
 		"import-fresh": "^3.3.1",
 		"jsonschema": "^1.5.0",
 		"merge-options": "^3.0.4",
@@ -38,9 +37,13 @@
 		"simple-mock": "^0.8.0",
 		"upath": "^2.0.1"
 	},
+	"peerDependencies": {
+		"eslint": ">=8.0.0"
+	},
 	"devDependencies": {
+		"c8": "^12.0.0",
+		"eslint": "^8.57.1",
 		"eslint-config-wikimedia": "^0.32.3",
-		"mocha": "^11.7.5",
-		"nyc": "^17.1.0"
+		"mocha": "^12.0.3"
 	}
 }

package/src/eslint.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const packagePath = require( './package-path' );
+
+/**
+ * Load a module from the plugin's copy of ESLint
+ *
+ * Docs should be built with the same version of ESLint, and the same config
+ * system, as the plugin's tests are run with.
+ *
+ * @param {string} [subpath] Module path within the ESLint package, e.g. 'use-at-your-own-risk'
+ * @return {Object} Module exports
+ */
+function requireESLint( subpath ) {
+	const name = subpath ? 'eslint/' + subpath : 'eslint';
+	// eslint-disable-next-line security/detect-non-literal-require
+	return require( require.resolve( name, { paths: [ packagePath( '.' ) ] } ) );
+}
+
+module.exports = requireESLint;

package/src/fix.js

@@ -1,47 +1,150 @@
 'use strict';
 
-const { Linter, ESLint } = require( 'eslint' );
-const linter = new Linter();
-const eslint = new ESLint();
+const requireESLint = require( './eslint' );
+const { Linter, ESLint, loadESLint } = requireESLint();
+const { builtinRules } = requireESLint( 'use-at-your-own-risk' );
 const mergeOptions = require( 'merge-options' );
-const { builtinRules } = require( 'eslint/use-at-your-own-risk' );
 
+/**
+ * ESLint 9+'s RuleTester only supports flat config, so test cases and the
+ * tester config are in flat config format.
+ */
+const isFlatRuleTester = parseInt( Linter.version, 10 ) >= 9;
+
+const linter = new Linter( { configType: isFlatRuleTester ? 'flat' : 'eslintrc' } );
+
+/**
+ * Get the plugin's ESLint config for its main file, normalized to a format
+ * which doesn't depend on the config system used
+ *
+ * Only fixable core rules are kept, as plugin rules would need the plugin to
+ * be loaded, and only fixes are needed.
+ *
+ * @return {Promise<Object>} Normalized config
+ */
 async function getConfig() {
-	const config = await eslint.calculateConfigForFile( require( './main' ) );
+	// loadESLint (ESLint 8.57+) returns the class for the config system used
+	// by the plugin, i.e. depending on whether it has an eslint.config.js file
+	const ESLintClass = loadESLint ? await loadESLint() : ESLint;
+	const eslint = new ESLintClass();
+	const config = await eslint.calculateConfigForFile( require( './main' ) ) || {};
+	const isFlatConfig = ESLintClass.configType === 'flat';
+	const languageOptions = ( isFlatConfig ? config.languageOptions : config.parserOptions ) || {};
 
-	// Optimization: Only use fixable rules
-	const fixableRules = {};
-	Object.keys( config.rules ).forEach( ( ruleName ) => {
+	const rules = {};
+	Object.keys( config.rules || {} ).forEach( ( ruleName ) => {
 		if ( builtinRules.has( ruleName ) ) {
 			const rule = builtinRules.get( ruleName );
 			if ( rule.meta.fixable ) {
-				fixableRules[ ruleName ] = config.rules[ ruleName ];
+				rules[ ruleName ] = config.rules[ ruleName ];
 			}
 		}
 	} );
-	config.rules = fixableRules;
 
-	return config;
+	return {
+		rules,
+		settings: config.settings,
+		// eslintrc only, can set the ecmaVersion, e.g. "es2017"
+		env: config.env,
+		// Parser name/path (eslintrc) or object (flat config)
+		parser: isFlatConfig ? languageOptions.parser : config.parser,
+		parserOptions: isFlatConfig ? languageOptions.parserOptions : config.parserOptions,
+		ecmaVersion: languageOptions.ecmaVersion,
+		sourceType: languageOptions.sourceType
+	};
+}
+
+/**
+ * Get a flat config array, for linting with ESLint 9+
+ *
+ * @param {Object} config Normalized config, from #getConfig
+ * @param {Object|Object[]} testerConfig RuleTester config
+ * @return {Object[]} Flat config array
+ */
+function getFlatConfig( config, testerConfig ) {
+	const baseConfig = {
+		rules: config.rules,
+		languageOptions: {}
+	};
+	if ( config.settings ) {
+		baseConfig.settings = config.settings;
+	}
+	[ 'ecmaVersion', 'sourceType', 'parserOptions' ].forEach( ( key ) => {
+		if ( config[ key ] !== undefined ) {
+			baseConfig.languageOptions[ key ] = config[ key ];
+		}
+	} );
+	if ( config.parser ) {
+		baseConfig.languageOptions.parser = typeof config.parser === 'string' ?
+			// eslint-disable-next-line security/detect-non-literal-require
+			require( config.parser ) :
+			config.parser;
+	}
+	// The RuleTester config may include rules which aren't loaded here,
+	// e.g. "rule-tester/validate-ast", and rules aren't needed for fixing.
+	const testerConfigs = [].concat( testerConfig || [] ).map( ( testerConfigItem ) => {
+		const copy = Object.assign( {}, testerConfigItem );
+		delete copy.rules;
+		return copy;
+	} );
+	return [ baseConfig, ...testerConfigs ];
+}
+
+/**
+ * Get an eslintrc config, for linting with ESLint 8
+ *
+ * @param {Object} config Normalized config, from #getConfig
+ * @param {Object} testerConfig RuleTester config
+ * @return {Object} eslintrc config
+ */
+function getEslintrcConfig( config, testerConfig ) {
+	const baseConfig = {
+		rules: config.rules,
+		parserOptions: Object.assign( {}, config.parserOptions )
+	};
+	if ( config.settings ) {
+		baseConfig.settings = config.settings;
+	}
+	if ( config.env ) {
+		baseConfig.env = config.env;
+	}
+	[ 'ecmaVersion', 'sourceType' ].forEach( ( key ) => {
+		if ( config[ key ] !== undefined ) {
+			baseConfig.parserOptions[ key ] = config[ key ];
+		}
+	} );
+	if ( config.parser ) {
+		baseConfig.parser = config.parser;
+	}
+
+	const mergedConfig = mergeOptions( baseConfig, testerConfig );
+
+	if ( mergedConfig.parser && typeof mergedConfig.parser !== 'string' ) {
+		// A parser object, from an ESLint 8.57 flat config
+		linter.defineParser( 'eslint-docgen-parser', mergedConfig.parser );
+		mergedConfig.parser = 'eslint-docgen-parser';
+	} else if ( typeof mergedConfig.parser === 'string' ) {
+		// eslint-disable-next-line security/detect-non-literal-require
+		linter.defineParser( mergedConfig.parser, require( mergedConfig.parser ) );
+	}
+
+	return mergedConfig;
 }
 
 /**
  * Lint and fix some code
  *
  * @param {string} code Code
- * @param {Object} testerConfig Config
+ * @param {Object|Object[]} testerConfig RuleTester config
  * @return {string} Fixed code
  */
 async function lintFix( code, testerConfig ) {
-	const mergedConfig = mergeOptions( await getConfig(), testerConfig );
+	const config = await getConfig();
 
-	// TODO
-	// istanbul ignore next
-	if ( typeof mergedConfig.parser === 'string' ) {
-		// eslint-disable-next-line security/detect-non-literal-require
-		linter.defineParser( mergedConfig.parser, require( mergedConfig.parser ) );
-	}
+	const result = isFlatRuleTester ?
+		linter.verifyAndFix( code, getFlatConfig( config, testerConfig ), { filename: 'example.js' } ) :
+		linter.verifyAndFix( code, getEslintrcConfig( config, testerConfig ) );
 
-	const result = linter.verifyAndFix( code, mergedConfig );
 	const err = result.messages.find( ( message ) => message.fatal );
 	// TODO
 	// istanbul ignore next
@@ -58,7 +161,7 @@ async function lintFix( code, testerConfig ) {
  * Concatenates the code snippets into one code block to improve performance
  *
  * @param {string[]} codeList Code list
- * @param {Object} testerConfig Config
+ * @param {Object|Object[]} testerConfig RuleTester config
  * @return {string[]} Fixed code list
  */
 async function batchLintFix( codeList, testerConfig ) {

package/src/rule-tester.js

@@ -1,9 +1,7 @@
 'use strict';
 
-const packagePath = require( './package-path' );
 // Use plugin's version of ESLint
-// eslint-disable-next-line security/detect-non-literal-require
-const ESLintRuleTester = require( packagePath( 'node_modules/eslint' ) ).RuleTester;
+const ESLintRuleTester = require( './eslint' )().RuleTester;
 const inDocMode = !!process.env.DOCGEN;
 
 /**

package/src/rules-with-config.js

@@ -11,10 +11,44 @@ rulesWithConfig.forEach( ( rule, name ) => {
 	rulesWithConfig.get( name ).configMap = new Map();
 } );
 
+/**
+ * Check if a config is a duplicate of another config in a different format
+ *
+ * Plugins which support both eslintrc and flat config often export each config
+ * twice, e.g. `recommended` and `flat/recommended`, or `recommended` and
+ * `legacy-recommended`. Only list these once.
+ *
+ * @param {string} name Config name
+ * @return {boolean}
+ */
+function isDuplicateConfig( name ) {
+	const match = name.match( /^(?:flat\/|legacy-)(.*)$/ );
+	return !!match && Object.prototype.hasOwnProperty.call( configs, match[ 1 ] );
+}
+
+/**
+ * Get the rules set by a config
+ *
+ * @param {Object|Object[]} config eslintrc config, flat config, or flat config array
+ * @return {Object} Rules
+ */
+function getRules( config ) {
+	return Array.isArray( config ) ?
+		Object.assign( {}, ...config.map( getRules ) ) :
+		config.rules || {};
+}
+
 // Iterate over configs to add config data to map
 for ( const name in configs ) {
-	const rules = configs[ name ].rules || {};
+	if ( isDuplicateConfig( name ) ) {
+		continue;
+	}
+	const rules = getRules( configs[ name ] );
 	for ( const fullName in rules ) {
+		// Flat config arrays can include rules from other plugins
+		if ( !fullName.startsWith( pluginName + '/' ) ) {
+			continue;
+		}
 		// Configs use the full rule name with the plugin prefix, so remove this
 		const shortName = fullName.slice( pluginName.length + 1 );
 		let options, rawSeverity;