eslint-docgen 0.7.1 → 0.8.0

package/README.md

@@ -116,6 +116,14 @@ When defined, will try to use a rule specific template instead of [`index.ejs`](
 #### `globalTemplatePath`
 When defined, templates in this path will override the global templates defined in [`src/templates`](src/templates).
 
+#### `readmeTemplate` (default `'README.md.template'`)
+File path containing a README template, with placeholders for a generated rules list (`<!-- rules -->`), and optionally deprecated rules (`<!-- deprecated -->`).
+
+Invoke by running `eslint-docgen-build-readme`.
+
+#### `readmeTarget` (default `'README.md'`)
+File path to write generated README to, after compiling `readmeTemplate`.
+
 #### `docLink` (default `false`)
 Add a link to the documentation source in the "Resources" section.
 
@@ -158,7 +166,7 @@ Number of spaces to convert tabs to in code examples. Tabs in examples are alway
 
 ## 🔍 Rules index
 
-To assist with building an index of your rules, for example to put in a root README, this package exports `rulesWithConfig`. The value is a Map much like the one returned by [Linter#getRules](https://eslint.org/docs/developer-guide/nodejs-api#linter-getrules) but each rule has an additional `configMap` property that describes which configs include the rule and the options used (`null` if no options are used).
+To assist with building an index of your rules, for example to put in a root README, this package exports `rulesWithConfig`. The value is a Map much like the one returned by [Linter#getRules](https://eslint.org/docs/developer-guide/nodejs-api#linter-getrules) but each rule has an additional `configMap` property that describes which configs include the rule, the severity (normalised to a string) and options used (`null` if none are used).
 
 Note that the rule names do not include the plugin prefix.
 
@@ -170,8 +178,9 @@ require( 'eslint-docgen' ).rulesWithConfig.get( 'no-event-shorthand' );
     meta: [Object],
     create: [Function],
     configMap: Map {
-        'deprecated-3.5' => null,
-        'deprecated-3.3' => [ { allowAjaxEvents: true } ]
+        'deprecated-4.0' => { severity: 'error', options: null },
+        'deprecated-3.5' => { severity: 'warn', options: null },
+        'deprecated-3.3' => { severity: 'warn', options: [ { allowAjaxEvents: true } ] }
     }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-docgen",
-	"version": "0.7.1",
+	"version": "0.8.0",
 	"description": "Automatically generate ESLint plugin documentation from rule metadata and test cases.",
 	"repository": {
 		"type": "git",
@@ -12,6 +12,9 @@
 		"documentation"
 	],
 	"main": "src/index.js",
+	"bin": {
+		"eslint-docgen-build-readme": "src/build-readme.js"
+	},
 	"files": [
 		"src"
 	],
@@ -20,25 +23,24 @@
 		"report": "nyc report --reporter=html"
 	},
 	"engines": {
-		"node": ">=12.0.0"
+		"node": ">=20.0.0"
 	},
 	"dependencies": {
 		"chalk": "^4.1.2",
-		"ejs": "^3.1.8",
+		"ejs": "^4.0.1",
 		"eslint": ">=8.0.0",
-		"import-fresh": "^3.3.0",
-		"jsonschema": "^1.4.1",
+		"import-fresh": "^3.3.1",
+		"jsonschema": "^1.5.0",
 		"merge-options": "^3.0.4",
-		"mkdirp": "^1.0.4",
+		"mkdirp": "^3.0.1",
 		"pkg-dir": "^5.0.0",
 		"pluralize": "^8.0.0",
 		"simple-mock": "^0.8.0",
 		"upath": "^2.0.1"
 	},
 	"devDependencies": {
-		"eslint-config-wikimedia": "^0.22.1",
-		"eslint-plugin-node": "^11.1.0",
-		"mocha": "^9.2.0",
-		"nyc": "^15.1.0"
+		"eslint-config-wikimedia": "^0.32.3",
+		"mocha": "^11.7.5",
+		"nyc": "^17.1.0"
 	}
 }

package/src/build-docs-from-tests.js

@@ -21,9 +21,10 @@ const languageFromExtension = {
  * @return {string} Concatenated list
  */
 function listFormatter( list ) {
-	return list.reduce( ( acc, cur, i, arr ) =>
-		acc + ( i === 0 ? '' : ( ( i === arr.length - 1 ) ? ' and ' : ', ' ) ) + cur,
-	'' );
+	return list.reduce(
+		( acc, cur, i, arr ) => acc + ( i === 0 ? '' : ( ( i === arr.length - 1 ) ? ' and ' : ', ' ) ) + cur,
+		''
+	);
 }
 
 /**
@@ -79,8 +80,8 @@ async function buildDocsFromTests(
 	}
 
 	async function buildRuleDetails( testList, isValid, showFixes ) {
-		testList = testList.filter( ( test ) =>
-			test.docgen === undefined ?
+		testList = testList.filter(
+			( test ) => test.docgen === undefined ?
 				!config.excludeExamplesByDefault :
 				test.docgen
 		);
@@ -100,12 +101,13 @@ async function buildDocsFromTests(
 
 		if ( showFixes ) {
 			// Calculate maxCodeLength for alignment
-			maxCodeLength = fixedCode.reduce( ( acc, code ) =>
-				code.split( '\n' ).reduce(
+			maxCodeLength = fixedCode.reduce(
+				( acc, code ) => code.split( '\n' ).reduce(
 					( lineAcc, line ) => Math.max( lineAcc, line.length ),
 					acc
 				),
-			0 );
+				0
+			);
 
 			const outputList = testList.map( ( test ) => test.output );
 			if ( config.fixCodeExamples ) {
@@ -120,7 +122,7 @@ async function buildDocsFromTests(
 
 		const codeSet = {};
 		let previousMultiLine = false;
-		testList.forEach( function ( test, i ) {
+		testList.forEach( ( test, i ) => {
 			const filename = getFilename( test );
 			let lang = 'js';
 			// Switch to Vue if we are showing file names and its a Vue file.
@@ -260,10 +262,12 @@ async function buildDocsFromTests(
 	let inConfigs = [];
 	if ( configMap ) {
 		inConfigs = Array.from( configMap.keys() ).map( ( configName ) => {
-			const options = configMap.get( configName );
+			const { options, severity } = configMap.get( configName );
+
 			return {
 				config: configName,
-				options: options && Object.keys( options[ 0 ] ).length ? JSON.stringify( options ) : ''
+				options: options && Object.keys( options[ 0 ] ).length ? JSON.stringify( options ) : '',
+				severity: severity
 			};
 		} );
 	}
@@ -271,11 +275,12 @@ async function buildDocsFromTests(
 	const invalid = await buildRuleDetails( tests.invalid, false );
 	const valid = await buildRuleDetails( tests.valid, true );
 
-	const validInvalid = invalid.concat( valid ).sort( ( a, b ) => {
-		return a.key === b.key ?
+	const validInvalid = invalid.concat( valid ).sort(
+		// sort by key, then value
+		( a, b ) => a.key === b.key ?
 			( a.valid < b.valid ? -1 : 1 ) :
-			( a.key < b.key ? -1 : 1 );
-	} );
+			( a.key < b.key ? -1 : 1 )
+	);
 
 	let fixed = [];
 	if ( ruleMeta.fixable && config.showFixExamples ) {
@@ -323,6 +328,7 @@ async function buildDocsFromTests(
 		const fs = require( 'fs' );
 		const packagePath = require( './package-path' );
 		const ruleTemplatePath = packagePath( config.ruleTemplatePath.replace( '{name}', name ) );
+		// eslint-disable-next-line security/detect-non-literal-fs-filename
 		if ( fs.existsSync( ruleTemplatePath ) ) {
 			index = loadRuleTemplate( ruleTemplatePath );
 		}

package/src/build-readme.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+const configRename = ( name ) => name.replace( 'deprecated-', '' );
+
+/**
+ * Build the README contents from a template
+ *
+ * @param {Object} config Resolved eslint-docgen config
+ * @param {Map} rulesWithConfig Map of rule names to rule data (meta and configMap)
+ * @param {string} template README template containing `<!-- rules -->` and
+ *  `<!-- deprecated -->` placeholders
+ * @return {string} README contents
+ */
+function buildReadme( config, rulesWithConfig, template ) {
+	function getRules( deprecated ) {
+		return Array.from( rulesWithConfig.keys() ).map( ( rule ) => {
+			const fullRule = config.pluginName + '/' + rule;
+			const ruleData = rulesWithConfig.get( rule );
+			const docs = ruleData.meta.docs;
+			const configs = Array.from( ruleData.configMap.keys() ).map( ( name ) => {
+				const { options, severity } = ruleData.configMap.get( name );
+				// TODO: Create util to compare options to defaults
+				return {
+					name: configRename( name ),
+					hasOptions: !!( options && Object.keys( options[ 0 ] ).length ),
+					severity
+				};
+			} );
+			// Sort configs by name - sort numerical values by version number
+			configs.sort( ( a, b ) => {
+				if ( a.name.includes( '.' ) === -1 ) {
+					return a.name.localeCompare( b.name );
+				}
+				const aVersion = a.name.split( '.' ).map( ( n ) => parseInt( n, 10 ) );
+				const bVersion = b.name.split( '.' ).map( ( n ) => parseInt( n, 10 ) );
+				for ( let i = 0; i < Math.max( aVersion.length, bVersion.length ); i++ ) {
+					if ( aVersion[ i ] !== bVersion[ i ] ) {
+						return ( aVersion[ i ] || 0 ) - ( bVersion[ i ] || 0 );
+					}
+				}
+				return 0;
+			} );
+			if ( !!docs.deprecated === deprecated ) {
+				return '* [`' + fullRule + '`](' + config.docPath.replace( '{name}', rule ) + ')' +
+					(
+						ruleData.meta.schema.length ?
+							' ⚙️' :
+							''
+					) +
+					(
+						ruleData.meta.fixable ?
+							' 🔧' :
+							''
+					) +
+					(
+						docs.replacedBy ?
+							' (use [`' + config.pluginName + '/' + docs.replacedBy + '`](' + config.docPath.replace( '{name}', docs.replacedBy ) + '))' :
+							''
+					) +
+					(
+						ruleData.configMap.size ?
+							' ' +
+							Array.from( configs ).map(
+								( c ) => ( c.severity === 'error' ? '**' : '' ) +
+									'`' + c.name + ( c.hasOptions ? '†' : '' ) + '`' +
+									( c.severity === 'error' ? '**' : '' ) ).join( ', ' ) :
+							''
+					);
+			}
+			return null;
+		} ).filter( ( rule ) => rule ).join( '\n' );
+	}
+
+	return `<!-- This file is built by eslint-docgen-build-readme. Do not edit it directly; edit ${ config.readmeTemplate } instead. -->\n` +
+		template
+			.replace( '<!-- rules -->', getRules( false ) )
+			.replace( '<!-- deprecated -->', getRules( true ) );
+}
+
+/* istanbul ignore next */
+function main() {
+	const fs = require( 'fs' );
+	const rulesWithConfig = require( './rules-with-config' );
+	const getConfig = require( './get-config' );
+
+	const config = getConfig();
+	// eslint-disable-next-line security/detect-non-literal-fs-filename
+	const template = fs.readFileSync( config.readmeTemplate, { encoding: 'UTF8' } );
+
+	// eslint-disable-next-line security/detect-non-literal-fs-filename
+	fs.writeFile(
+		config.readmeTarget,
+		buildReadme( config, rulesWithConfig, template ),
+		( err ) => {
+			if ( err ) {
+				throw err;
+			}
+		}
+	);
+}
+
+/* istanbul ignore next */
+if ( require.main === module ) {
+	main();
+}
+
+module.exports = buildReadme;

package/src/config-schema.json

@@ -21,6 +21,8 @@
 			"type": "null",
 			"message": "must be renamed to \"globalTemplatePath\""
 		},
+		"readmeTemplate": { "type": "string" },
+		"readmeTarget": { "type": "string" },
 		"docLink": { "type": "boolean" },
 		"ruleLink": { "type": "boolean" },
 		"testLink": { "type": "boolean" },

package/src/default-config.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const packagePath = require( './package-path' );
+// eslint-disable-next-line security/detect-non-literal-require
 const packageName = require( packagePath( './package' ) ).name;
 const naming = require( './naming' );
 const pluginName = naming.getShorthandName( packageName, 'eslint-plugin' );
@@ -17,6 +18,8 @@ module.exports = {
 	testPath: null,
 	ruleTemplatePath: null,
 	globalTemplatePath: null,
+	readmeTemplate: 'README.md.template',
+	readmeTarget: 'README.md',
 	docLink: false,
 	ruleLink: true,
 	testLink: true,

package/src/fix.js

@@ -4,7 +4,6 @@ const { Linter, ESLint } = require( 'eslint' );
 const linter = new Linter();
 const eslint = new ESLint();
 const mergeOptions = require( 'merge-options' );
-// eslint-disable-next-line node/no-missing-require
 const { builtinRules } = require( 'eslint/use-at-your-own-risk' );
 
 async function getConfig() {
@@ -12,7 +11,7 @@ async function getConfig() {
 
 	// Optimization: Only use fixable rules
 	const fixableRules = {};
-	Object.keys( config.rules ).forEach( function ( ruleName ) {
+	Object.keys( config.rules ).forEach( ( ruleName ) => {
 		if ( builtinRules.has( ruleName ) ) {
 			const rule = builtinRules.get( ruleName );
 			if ( rule.meta.fixable ) {
@@ -38,6 +37,7 @@ async function lintFix( code, testerConfig ) {
 	// 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 ) );
 	}
 

package/src/formatter.js

@@ -20,8 +20,8 @@ function labelSuffix( label ) {
  * @return {string}
  */
 function indentAfterFirst( text, indent ) {
-	return text.split( '\n' ).map( ( line, i ) =>
-		i ? ' '.repeat( indent ) + line : line
+	return text.split( '\n' ).map(
+		( line, i ) => i ? ' '.repeat( indent ) + line : line
 	).join( '\n' );
 }
 

package/src/get-config.js

@@ -3,6 +3,8 @@
 const fs = require( 'fs' );
 const packagePath = require( './package-path' );
 const importFresh = require( 'import-fresh' );
+const validateConfig = require( './validate-config' );
+const formatter = require( './formatter' );
 
 const configFilenames = [
 	'.eslintdocgenrc.js',
@@ -15,6 +17,7 @@ const configFilenames = [
  * Missing values are backfilled with the defaults
  *
  * @return {Object} Config
+ * @throws {Error} If no config file is found, or if the config is invalid
  */
 function getConfig() {
 	let config, configPath;
@@ -22,6 +25,7 @@ function getConfig() {
 	configFilenames.some( ( configFilename ) => {
 		configPath = packagePath( configFilename );
 
+		// eslint-disable-next-line security/detect-non-literal-fs-filename
 		if ( fs.existsSync( configPath ) ) {
 			config = importFresh( configPath );
 			return true;
@@ -30,16 +34,18 @@ function getConfig() {
 	} );
 
 	if ( !config ) {
-		throw new Error( '.eslintdocgenrc not found' );
+		throw new Error( [ formatter.heading( 'eslint-docgen' ), formatter.error( '.eslintdocgenrc not found' ) ].join( '\n' ) );
 	}
 
 	const defaultConfig = require( './default-config.js' );
 	config = Object.assign( {}, defaultConfig, config );
 
-	return {
-		config: config,
-		configPath: configPath
-	};
+	const configErrors = validateConfig( config );
+	if ( configErrors.length ) {
+		throw new Error( [ formatter.heading( configPath ), ...configErrors.map( formatter.error ) ].join( '\n' ) );
+	}
+
+	return config;
 }
 
 module.exports = getConfig;

package/src/load-templates.js

@@ -5,10 +5,12 @@ const path = require( 'upath' );
 const ejs = require( 'ejs' );
 
 function loadTemplatesFromPath( dirPath ) {
+	// eslint-disable-next-line security/detect-non-literal-fs-filename
 	const files = fs.readdirSync( dirPath );
 	const templates = {};
 	files.forEach( ( filename ) => {
 		templates[ path.parse( filename ).name ] =
+			// eslint-disable-next-line security/detect-non-literal-fs-filename
 			fs.readFileSync( path.join( dirPath, filename ) ).toString();
 	} );
 	return templates;
@@ -31,14 +33,13 @@ function loadTemplates( dirPaths ) {
 
 	function compile( string, filename ) {
 		const compiled = ejs.compile( string, { client: true } );
-		return ( data ) =>
-			compiled( data, null, function ( template, includeData ) {
-				const mergedData = Object.assign( {}, data, includeData );
-				if ( !hasOwn.call( templateStrings, template ) ) {
-					throw new Error( 'Template `' + template + '` not found in template `' + filename + '`' );
-				}
-				return globalTemplates[ template ]( mergedData );
-			} );
+		return ( data ) => compiled( data, null, ( template, includeData ) => {
+			const mergedData = Object.assign( {}, data, includeData );
+			if ( !hasOwn.call( templateStrings, template ) ) {
+				throw new Error( 'Template `' + template + '` not found in template `' + filename + '`' );
+			}
+			return globalTemplates[ template ]( mergedData );
+		} );
 	}
 
 	Object.keys( templateStrings ).forEach( ( filename ) => {
@@ -47,6 +48,7 @@ function loadTemplates( dirPaths ) {
 
 	function loadRuleTemplate( ruleTemplatePath ) {
 		return compile(
+			// eslint-disable-next-line security/detect-non-literal-fs-filename
 			fs.readFileSync( ruleTemplatePath ).toString()
 		);
 	}

package/src/main.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const packagePath = require( './package-path' );
+// eslint-disable-next-line security/detect-non-literal-require
 const main = require( packagePath( './package' ) ).main || 'index.js';
 
 module.exports = packagePath( main );

package/src/naming.js

@@ -14,17 +14,19 @@
  */
 function getShorthandName( fullname, prefix ) {
 	if ( fullname[ 0 ] === '@' ) {
-		let matchResult = new RegExp( `^(@[^/]+)/${prefix}$`, 'u' ).exec( fullname );
+		// eslint-disable-next-line security/detect-non-literal-regexp
+		let matchResult = new RegExp( `^(@[^/]+)/${ prefix }$`, 'u' ).exec( fullname );
 
 		if ( matchResult ) {
 			return matchResult[ 1 ];
 		}
 
-		matchResult = new RegExp( `^(@[^/]+)/${prefix}-(.+)$`, 'u' ).exec( fullname );
+		// eslint-disable-next-line security/detect-non-literal-regexp
+		matchResult = new RegExp( `^(@[^/]+)/${ prefix }-(.+)$`, 'u' ).exec( fullname );
 		if ( matchResult ) {
-			return `${matchResult[ 1 ]}/${matchResult[ 2 ]}`;
+			return `${ matchResult[ 1 ] }/${ matchResult[ 2 ] }`;
 		}
-	} else if ( fullname.startsWith( `${prefix}-` ) ) {
+	} else if ( fullname.startsWith( `${ prefix }-` ) ) {
 		return fullname.slice( prefix.length + 1 );
 	}
 

package/src/rule-tester.js

@@ -2,6 +2,7 @@
 
 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 inDocMode = !!process.env.DOCGEN;
 

package/src/rules-with-config.js

@@ -1,7 +1,8 @@
 'use strict';
 
+// eslint-disable-next-line security/detect-non-literal-require
 const main = require( require( './main' ) );
-const pluginName = require( './get-config' )().config.pluginName;
+const pluginName = require( './get-config' )().pluginName;
 const configs = main.configs;
 const rulesWithConfig = new Map( Object.entries( main.rules ) );
 
@@ -16,9 +17,26 @@ for ( const name in configs ) {
 	for ( const fullName in rules ) {
 		// Configs use the full rule name with the plugin prefix, so remove this
 		const shortName = fullName.slice( pluginName.length + 1 );
+		let options, rawSeverity;
+
+		if ( Array.isArray( rules[ fullName ] ) ) {
+			options = rules[ fullName ].slice( 1 );
+			rawSeverity = rules[ fullName ][ 0 ];
+		} else {
+			options = null;
+			rawSeverity = rules[ fullName ];
+		}
+		const severityMap = [ 'off', 'warn', 'error' ];
+		const severity = typeof rawSeverity === 'number' ?
+			severityMap[ rawSeverity ] || 'error' :
+			rawSeverity;
+
 		rulesWithConfig.get( shortName ).configMap.set(
 			name,
-			Array.isArray( rules[ fullName ] ) ? rules[ fullName ].slice( 1 ) : null
+			{
+				severity,
+				options
+			}
 		);
 	}
 }

package/src/templates/inConfig.ejs

@@ -1 +1 @@
-📋 This rule is enabled in `plugin:<%- pluginName %>/<%- inConfig.config %>`<%- include( 'optionsAndSettings', { data: inConfig } ) %>.
+📋 This rule is enabled as <%- inConfig.severity === 'warn' ? 'a warning' : 'an error' %> in `plugin:<%- pluginName %>/<%- inConfig.config %>`<%- include( 'optionsAndSettings', { data: inConfig } ) %>.

package/src/validate-config.js

@@ -11,8 +11,7 @@ const schema = require( './config-schema' );
  * @return {string[]} A list of errors found
  */
 function validateConfig( config ) {
-	const errors = v.validate( config, schema ).errors.map( ( e ) =>
-		e.schema.message ? e.property + ' ' + e.schema.message : e.stack );
+	const errors = v.validate( config, schema ).errors.map( ( e ) => e.schema.message ? e.property + ' ' + e.schema.message : e.stack );
 
 	return errors;
 }

package/src/write-docs-from-tests.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const fs = require( 'fs' );
-const mkdirp = require( 'mkdirp' );
+const { mkdirp } = require( 'mkdirp' );
 const path = require( 'upath' );
 const buildDocsFromTests = require( './build-docs-from-tests' );
 
@@ -9,23 +9,16 @@ const formatter = require( './formatter' );
 const rulesWithConfig = require( './rules-with-config' );
 
 const getConfig = require( './get-config' );
-let config, configPath;
-try {
-	( { config, configPath } = getConfig() );
-} catch ( e ) {
-	throw new Error( [ formatter.heading( 'eslint-docgen' ), formatter.error( e.message ) ].join( '\n' ) );
-}
+const config = getConfig();
 
-const configValidator = require( './validate-config' );
+const validateConfig = require( './validate-config' );
 function assertValidConfig( maybeValidConfig, configSource ) {
-	const configErrors = configValidator( maybeValidConfig );
+	const configErrors = validateConfig( maybeValidConfig );
 	if ( configErrors.length ) {
 		throw new Error( [ formatter.heading( configSource ), ...configErrors.map( formatter.error ) ].join( '\n' ) );
 	}
 }
 
-assertValidConfig( config, configPath );
-
 const packagePath = require( './package-path' );
 
 const loadTemplates = require( './load-templates' );
@@ -61,6 +54,7 @@ async function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
 
 	const outputDir = path.dirname( outputPath );
 	mkdirp( outputDir ).then( () => {
+		// eslint-disable-next-line security/detect-non-literal-fs-filename
 		fs.writeFile(
 			outputPath,
 			output,
@@ -71,8 +65,8 @@ async function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
 				if ( messages.length ) {
 					console.log();
 					console.log( formatter.heading( outputPath ) );
-					messages.forEach( ( message ) =>
-						console.log( formatter[ message.type ]( message.text, message.label ) )
+					messages.forEach(
+						( message ) => console.log( formatter[ message.type ]( message.text, message.label ) )
 					);
 					console.log();
 				}