eslint-docgen 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-docgen",
-	"version": "0.5.1",
+	"version": "0.7.0",
 	"description": "Automatically generate ESLint plugin documentation from rule metadata and test cases.",
 	"repository": {
 		"type": "git",
@@ -25,7 +25,7 @@
 	"dependencies": {
 		"chalk": "^4.1.2",
 		"ejs": "^3.1.6",
-		"eslint": ">=5.0.0",
+		"eslint": ">=8.0.0",
 		"import-fresh": "^3.3.0",
 		"jsonschema": "^1.4.0",
 		"merge-options": "^3.0.4",
@@ -36,9 +36,9 @@
 		"upath": "^2.0.1"
 	},
 	"devDependencies": {
-		"eslint-config-wikimedia": "^0.20.0",
+		"eslint-config-wikimedia": "^0.22.1",
 		"eslint-plugin-node": "^11.1.0",
-		"mocha": "^9.1.3",
+		"mocha": "^9.2.0",
 		"nyc": "^15.1.0"
 	}
 }

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

@@ -2,6 +2,13 @@
 
 const pluralize = require( 'pluralize' );
 const path = require( 'upath' );
+// Mapping from extension to language name for markdown
+// Default language is 'js'
+const languageFromExtension = {
+	'.html': 'html',
+	'.ts': 'ts',
+	'.vue': 'vue'
+};
 
 /**
  * Format a list of items with natural language
@@ -30,7 +37,7 @@ function mdLink( target, label ) {
 	return '[' + label + '](' + target + ')';
 }
 
-function buildDocsFromTests(
+async function buildDocsFromTests(
 	name, ruleMeta, tests, configMap, config, globalTemplates, loadRuleTemplate, testerConfig
 ) {
 
@@ -60,28 +67,31 @@ function buildDocsFromTests(
 	}
 
 	/**
-	 *
-	 * @param {string|Object} test
-	 * @return {string|undefined} The base file name, or undefined if not set
+	 * @param {string|Object} test Test case
+	 * @return {string|null} The base file name, or null if not set
 	 */
 	function getFilename( test ) {
 		if ( typeof test === 'string' || test.filename === undefined ) {
-			// Either the test is just a code snippet, or its an object but with
-			// no file name set
-			return undefined;
+			// Either the test is just a code snippet, or no file name is set
+			return null;
 		}
-		// We don't need the full file path, just the last bit with the name and extension
 		return path.basename( test.filename );
 	}
 
-	function buildRuleDetails( testList, valid, showFixes ) {
+	async function buildRuleDetails( testList, isValid, showFixes ) {
+		testList = testList.filter( ( test ) =>
+			test.docgen === undefined ?
+				!config.excludeExamplesByDefault :
+				test.docgen
+		);
+
 		let fixedCode, fixedOutput, maxCodeLength;
 		const testsByOptions = {};
 
 		const codeList = testList.map( getCode );
 		if ( config.fixCodeExamples ) {
 			const fix = require( './fix' );
-			fixedCode = fix.batchLintFix( codeList, testerConfig );
+			fixedCode = await fix.batchLintFix( codeList, testerConfig );
 		} else {
 			fixedCode = codeList;
 		}
@@ -100,7 +110,7 @@ function buildDocsFromTests(
 			const outputList = testList.map( ( test ) => test.output );
 			if ( config.fixCodeExamples ) {
 				const fix = require( './fix' );
-				fixedOutput = fix.batchLintFix( outputList, testerConfig );
+				fixedOutput = await fix.batchLintFix( outputList, testerConfig );
 			} else {
 				fixedOutput = outputList;
 			}
@@ -111,39 +121,37 @@ function buildDocsFromTests(
 		const codeSet = {};
 		let previousMultiLine = false;
 		testList.forEach( function ( test, i ) {
-			if ( !config.excludeExamplesByDefault && test.noDoc ) {
-				messages.push( {
-					type: 'warn',
-					text: '`noDoc: true` is deprecated. Use `docgen: false` instead.'
-				} );
-				return;
+			const filename = getFilename( test );
+			let lang = 'js';
+			// Switch to Vue if we are showing file names and its a Vue file.
+			// optionsAndSettings.filename is only set if it should be shown
+			// TODO should we add other languages too?
+			if ( filename ) {
+				const ext = path.extname( filename );
+				if ( ext in languageFromExtension ) {
+					lang = languageFromExtension[ ext ];
+				}
 			}
 
-			const docgen = test.docgen === undefined ?
-				!config.excludeExamplesByDefault :
-				test.docgen;
-
-			if ( !docgen ) {
-				return;
-			}
+			// Keys are in reverse sort order, e.g. examples with options
+			// are shown before examples with settings
+			const optionsAndSettings = {
+				// Always separate tests by language for syntax highlighting
+				lang: lang,
+				settings: test.settings,
+				options: test.options,
+				// Only group by filename if filenames are shown
+				filename: config.showFilenames && filename
+			};
+			const hashObject = {};
+			// Ensure examples without a specific key are shown first
+			Object.keys( optionsAndSettings ).forEach( ( key ) => {
+				hashObject[ key ] = optionsAndSettings[ key ] ?
+					[ '1', optionsAndSettings[ key ] ] :
+					[ '0', optionsAndSettings[ key ] ];
+			} );
 
-			let optionsAndSettings;
-			// Only include the filename if it should be shown
-			// Don't create an object if there are no options or settings and the file name is not
-			// set, so that those examples are sorted to the top of the docs
-			if (
-				test.options || test.settings ||
-				( config.showFilenames && getFilename( test ) )
-			) {
-				optionsAndSettings = {
-					options: test.options,
-					settings: test.settings
-				};
-				if ( config.showFilenames ) {
-					optionsAndSettings.filename = getFilename( test );
-				}
-			}
-			const hash = optionsAndSettings ? JSON.stringify( optionsAndSettings ) : '';
+			const hash = JSON.stringify( hashObject );
 
 			codeSet[ hash ] = codeSet[ hash ] || {};
 
@@ -168,9 +176,8 @@ function buildDocsFromTests(
 				};
 
 			if ( showFixes && test.output ) {
-				const output = fixedOutput[ i ];
 				const codeLines = code.split( '\n' );
-				const outputLines = output.split( '\n' );
+				const outputLines = fixedOutput[ i ].split( '\n' );
 				const maxLines = Math.max( codeLines.length, outputLines.length );
 				const exampleLines = [];
 				for ( let l = 0; l < maxLines; l++ ) {
@@ -188,7 +195,8 @@ function buildDocsFromTests(
 				example = code;
 				multiLine = code.split( '\n' ).length > 1;
 			}
-			if ( multiLine || previousMultiLine ) {
+			// Put linebreaks around multi-line examples
+			if ( testsByOptions[ hash ].tests.length && ( multiLine || previousMultiLine ) ) {
 				example = '\n' + example;
 			}
 			testsByOptions[ hash ].tests.push( example );
@@ -207,18 +215,19 @@ function buildDocsFromTests(
 			if ( config.fixCodeExamples ) {
 				const fix = require( './fix' );
 				// Fixes whitespace in block comment. Too expensive for such a small fix?
-				comments = fix.batchLintFix( comments, testerConfig );
+				comments = await fix.batchLintFix( comments, testerConfig );
 			}
 		}
 
 		return Object.keys( testsByOptions ).map( ( key, i ) => {
 			const section = testsByOptions[ key ];
 			const optionsAndSettings = section.optionsAndSettings;
+			const lang = optionsAndSettings && optionsAndSettings.lang;
 			const options = optionsAndSettings && optionsAndSettings.options;
 			const settings = optionsAndSettings && optionsAndSettings.settings;
 			const filename = optionsAndSettings && optionsAndSettings.filename;
 
-			let examples = '```js\n';
+			let examples = '```' + lang + '\n';
 			if ( config.showConfigComments ) {
 				examples += comments[ i ] + '\n';
 			}
@@ -227,7 +236,7 @@ function buildDocsFromTests(
 
 			return {
 				key: key,
-				valid: valid,
+				valid: isValid,
 				options: options ? JSON.stringify( options ) : '',
 				settings: settings ? JSON.stringify( settings ) : '',
 				filename: filename || '',
@@ -259,8 +268,8 @@ function buildDocsFromTests(
 		} );
 	}
 
-	const invalid = buildRuleDetails( tests.invalid, false );
-	const valid = buildRuleDetails( tests.valid, true );
+	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 ?
@@ -270,7 +279,7 @@ function buildDocsFromTests(
 
 	let fixed = [];
 	if ( ruleMeta.fixable && config.showFixExamples ) {
-		fixed = buildRuleDetails(
+		fixed = await buildRuleDetails(
 			tests.invalid.filter( ( test ) => !!test.output ),
 			false,
 			true

package/src/fix.js

@@ -1,23 +1,29 @@
 'use strict';
 
-const eslint = require( 'eslint' );
-const linter = new eslint.Linter();
-const cli = new eslint.CLIEngine();
-const config = cli.getConfigForFile( require( './main' ) );
-const rules = cli.getRules();
+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' );
 
-// Optimization: Only use fixable rules
-const fixableRules = {};
-Object.keys( config.rules ).forEach( function ( ruleName ) {
-	if ( rules.has( ruleName ) ) {
-		const rule = rules.get( ruleName );
-		if ( rule.meta.fixable ) {
-			fixableRules[ ruleName ] = config.rules[ ruleName ];
+async function getConfig() {
+	const config = await eslint.calculateConfigForFile( require( './main' ) );
+
+	// Optimization: Only use fixable rules
+	const fixableRules = {};
+	Object.keys( config.rules ).forEach( function ( ruleName ) {
+		if ( builtinRules.has( ruleName ) ) {
+			const rule = builtinRules.get( ruleName );
+			if ( rule.meta.fixable ) {
+				fixableRules[ ruleName ] = config.rules[ ruleName ];
+			}
 		}
-	}
-} );
-config.rules = fixableRules;
+	} );
+	config.rules = fixableRules;
+
+	return config;
+}
 
 /**
  * Lint and fix some code
@@ -26,8 +32,8 @@ config.rules = fixableRules;
  * @param {Object} testerConfig Config
  * @return {string} Fixed code
  */
-function lintFix( code, testerConfig ) {
-	const mergedConfig = mergeOptions( config, testerConfig );
+async function lintFix( code, testerConfig ) {
+	const mergedConfig = mergeOptions( await getConfig(), testerConfig );
 
 	// TODO
 	// istanbul ignore next
@@ -55,11 +61,12 @@ function lintFix( code, testerConfig ) {
  * @param {Object} testerConfig Config
  * @return {string[]} Fixed code list
  */
-function batchLintFix( codeList, testerConfig ) {
+async function batchLintFix( codeList, testerConfig ) {
 	const separator = '\n/* - */\n';
 	const codeBlock = codeList.join( ';' + separator );
 	// Add an extra semicolon to avoid syntax error
-	return lintFix( codeBlock, testerConfig ).split( separator ).map( ( code ) => code.trim() );
+	const fixed = await lintFix( codeBlock, testerConfig );
+	return fixed.split( separator ).map( ( code ) => code.trim() );
 }
 
 module.exports = {

package/src/rule-tester.js

@@ -3,37 +3,26 @@
 const packagePath = require( './package-path' );
 // Use plugin's version of ESLint
 const ESLintRuleTester = require( packagePath( 'node_modules/eslint' ) ).RuleTester;
-const docMode = !!process.env.DOCGEN || process.argv.includes( '--doc' );
-
-if ( process.argv.includes( '--doc' ) ) {
-	const formatter = require( './formatter' );
-	console.log(
-		formatter.warn( '--doc is deprecated, use the DOCGEN=1 environment variable instead.' )
-	);
-}
+const inDocMode = !!process.env.DOCGEN;
 
 /**
  * Extends ESLint's RuleTester to also build documentation
  */
 class RuleTester extends ESLintRuleTester {
 	run( name, rule, tests ) {
-		if ( docMode ) {
+		if ( inDocMode ) {
 			RuleTester.it( name, ( done ) => {
 				const writeDocsFromTests = require( './write-docs-from-tests' );
 				writeDocsFromTests( name, rule, tests, this.testerConfig, done );
 			} );
 		} else {
-			// Filter out invalid property "noDoc"
+			// Filter out invalid property "docgen"
 			// (used in documentation building mode).
 			tests.valid.forEach( ( test ) => {
 				delete test.docgen;
-				// Deprecated
-				delete test.noDoc;
 			} );
 			tests.invalid.forEach( ( test ) => {
 				delete test.docgen;
-				// Deprecated
-				delete test.noDoc;
 			} );
 
 			// Filter out invalid top level property "docgenConfig"

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

@@ -1,6 +1,5 @@
 'use strict';
 
-/* eslint-disable no-process-exit */
 const fs = require( 'fs' );
 const mkdirp = require( 'mkdirp' );
 const path = require( 'upath' );
@@ -14,20 +13,14 @@ let config, configPath;
 try {
 	( { config, configPath } = getConfig() );
 } catch ( e ) {
-	console.log( formatter.heading( 'eslint-docgen' ) );
-	console.log( formatter.error( e.message ) );
-	console.log();
-	process.exit( 1 );
+	throw new Error( [ formatter.heading( 'eslint-docgen' ), formatter.error( e.message ) ].join( '\n' ) );
 }
 
 const configValidator = require( './validate-config' );
 function assertValidConfig( maybeValidConfig, configSource ) {
 	const configErrors = configValidator( maybeValidConfig );
 	if ( configErrors.length ) {
-		console.log( formatter.heading( configSource ) );
-		configErrors.forEach( ( error ) => console.log( formatter.error( error ) ) );
-		console.log();
-		process.exit( 1 );
+		throw new Error( [ formatter.heading( configSource ), ...configErrors.map( formatter.error ) ].join( '\n' ) );
 	}
 }
 
@@ -42,7 +35,7 @@ if ( config.globalTemplatePath ) {
 }
 const { globalTemplates, loadRuleTemplate } = loadTemplates( templatePaths );
 
-function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
+async function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
 	// If the tests have a `docgenConfig` property, this overrides the global configuration
 	let configForRule = config;
 	if ( tests.docgenConfig !== undefined ) {
@@ -53,25 +46,17 @@ function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
 	const outputPath = packagePath( configForRule.docPath.replace( '{name}', name ) );
 	const ruleWithConfig = rulesWithConfig.get( name );
 	if ( !ruleWithConfig ) {
-		console.log();
-		console.log( formatter.heading( outputPath ) );
-		console.log( formatter.error( 'Rule not found.' ) );
-		console.log();
-		process.exit( 1 );
+		throw new Error( [ formatter.heading( outputPath ), formatter.error( 'Rule not found.' ) ].join( '\n' ) );
 	}
 	const configMap = rulesWithConfig.get( name ).configMap;
 	let output, messages;
 	try {
-		( { output, messages } = buildDocsFromTests(
+		( { output, messages } = await buildDocsFromTests(
 			name, rule.meta, tests, configMap, configForRule,
 			globalTemplates, loadRuleTemplate, testerConfig
 		) );
 	} catch ( e ) {
-		console.log();
-		console.log( formatter.heading( outputPath ) );
-		console.log( formatter.error( e.message ) );
-		console.log();
-		process.exit( 1 );
+		throw new Error( [ formatter.heading( outputPath ), formatter.error( e.message ) ].join( '\n' ) );
 	}
 
 	const outputDir = path.dirname( outputPath );
@@ -92,8 +77,10 @@ function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
 					console.log();
 				}
 
-				if ( messages.some( ( message ) => message.type === 'error' ) ) {
-					process.exit( 1 );
+				const errors = messages.filter( ( message ) => message.type === 'error' );
+
+				if ( errors.length ) {
+					throw new Error( errors.map( formatter.error ).join( '\n' ) );
 				}
 
 				done();