eslint-docgen 0.6.1 → 0.7.1

package/README.md

@@ -25,6 +25,18 @@ To build your documentation, run your rule tests with the `DOCGEN` environment v
 DOCGEN=1 mocha tests/rules/
 ```
 
+You could add this to your package.json to make it available as `npm run doc`, e.g.
+```jsonc
+{
+    //
+    "scripts": {
+        //
+        "doc": "rm -rf docs/rules && DOCGEN=1 mochan tests/rules/"
+    }
+    //
+}
+```
+
 Documentation will be built using **rule metadata** and **test data** passed to `RuleTester`:
 
 #### `rule.meta.docs.description`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-docgen",
-	"version": "0.6.1",
+	"version": "0.7.1",
 	"description": "Automatically generate ESLint plugin documentation from rule metadata and test cases.",
 	"repository": {
 		"type": "git",
@@ -24,10 +24,10 @@
 	},
 	"dependencies": {
 		"chalk": "^4.1.2",
-		"ejs": "^3.1.6",
-		"eslint": ">=5.0.0",
+		"ejs": "^3.1.8",
+		"eslint": ">=8.0.0",
 		"import-fresh": "^3.3.0",
-		"jsonschema": "^1.4.0",
+		"jsonschema": "^1.4.1",
 		"merge-options": "^3.0.4",
 		"mkdirp": "^1.0.4",
 		"pkg-dir": "^5.0.0",
@@ -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

@@ -37,7 +37,7 @@ function mdLink( target, label ) {
 	return '[' + label + '](' + target + ')';
 }
 
-function buildDocsFromTests(
+async function buildDocsFromTests(
 	name, ruleMeta, tests, configMap, config, globalTemplates, loadRuleTemplate, testerConfig
 ) {
 
@@ -78,7 +78,7 @@ function buildDocsFromTests(
 		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 :
@@ -91,7 +91,7 @@ function buildDocsFromTests(
 		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;
 		}
@@ -110,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;
 			}
@@ -176,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++ ) {
@@ -216,7 +215,7 @@ 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 );
 			}
 		}
 
@@ -237,7 +236,7 @@ function buildDocsFromTests(
 
 			return {
 				key: key,
-				valid: valid,
+				valid: isValid,
 				options: options ? JSON.stringify( options ) : '',
 				settings: settings ? JSON.stringify( settings ) : '',
 				filename: filename || '',
@@ -269,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 ?
@@ -280,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,13 +32,13 @@ 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
-	if ( testerConfig && typeof testerConfig.parser === 'string' ) {
-		linter.defineParser( testerConfig.parser, require( testerConfig.parser ) );
+	if ( typeof mergedConfig.parser === 'string' ) {
+		linter.defineParser( mergedConfig.parser, require( mergedConfig.parser ) );
 	}
 
 	const result = linter.verifyAndFix( code, mergedConfig );
@@ -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/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();

package/Changelog.md

@@ -1,99 +0,0 @@
-# eslint-docgen release history
-
-## v0.6.1
-* Fix: Filter out docgen:false tests before parsing (#120)
-
-## v0.6.0
-* Breaking change: Drop deprecated 'noDoc' option and '--doc' CLI flag (#115)
-* New: build-docs-from-tests: add Vue syntax highlighting (#105) (DannyS712)
-* New: Add TypeScript syntax highlighting
-* New: Add HTML syntax highlighting
-* New: Separate syntax highlighting support from showFilenames (#114)
-* Fix: Don't put an empty line before the first multi-line examples in a set (#117)
-* Code: Cleanup code for detecting highlight language (#113)
-
-## v0.5.1
-* Breaking change: Change the default icon for rules which are included in a preset (#109)
-* Breaking change: Add generated-file-warning comment to the top of MD files (#107)
-* Breaking change: Drop support for Node 10 (#110)
-* New: Add configuration to show file names for test cases (#101) (DannyS712)
-* New: Add per-rule config overrides (DannyS7123)
-* Docs: Various README fixes
-* Code: Update dependencies
-
-## v0.4.5
-* Code: Update dependencies
-
-## v0.4.4
-
-* Code: Ensure config.docPath exists before writing output path. (Raine Revere)
-* Code: Calculate outputDir from outputPath
-* Code: Fix reporting of writeFile error messages
-* Code: Output formatted error when rule not found (#92)
-* Docs: Fix config param heading level in README (#91)
-
-## v0.4.3
-
-* Code: Run one test 'it' per rule
-
-## v0.4.2
-
-* New: Introduce excludeExamplesByDefault config
-* Code: Remove some whitespace in config-schema
-* Code: Add a 'report' script
-
-## v0.4.1
-
-* Code: Update mocha to 8.0.1
-* Code: Replace path with upath for windows compatibility (#83)
-* Code: Use DOCGEN environment variable instead of --doc flag
-* Code: Add an editorconfig to make the tabs a reasonable width on GitHub (Jed Fox)
-* Code: Allow package.main to be empty
-* Code: Support scoped plugin names
-* Docs: Add more method documentation
-* Docs: Fix external links to examples
-* Docs: Add Migration section to README and move some pieces around
-
-## v0.4.0
-
-* Breaking change: New: Add fix message to introduction (#49)
-* Breaking change: New: Format long lists correctly ("a, b, and c")
-* Breaking change: New: Sort examples by options *then* valid/invalid (#48)
-* New: Refactor rulesData to rulesWithConfig and expose (#16)
-* New: Add ruleTemplatePath config (#14)
-* New: Add showFixExamples config (#49)
-* Code: Update eslint-config-wikimedia to 0.16.1 and use /mocha
-* Code: Use pkg-dir
-* Code: Create a JSON-schema to validate configs (#63)
-* Code: Update various dependencies
-* Tests: Separate config tests into get/validate
-* Tests: Increase timeout
-* Tests: Separate buildDocsFromTests cases
-* Docs: Fix example docpath
-
-## v0.3.1
-
-* Fix: Use plugin's version of ESLint
-
-## v0.3.0
-
-* Breaking change: New: Support multi-line test cases (#34)
-* New: Support multiple lines in formatter
-* New: Add min/maxExamples to config (#29)
-* New: Use chalk to do pretty output of warnings/errors (#38)
-* Code: Bump node dependency to 10 (#44)
-* Code: Use strict mode
-* Code: Use eslint-plugin-node/recommended
-* Code: Removed fixed length truncation from rules-data.js
-* Tests: Add tests for most utils (#39)
-* Tests: Increase code coverage to 100%
-* Docs: Add "plugin" to description
-
-## v0.2.0
-
-* Breaking change: Refactor templates. Users with existing template overrides will need to rewrite them.
-* Release: Update ejs to 3.1.3
-
-## v0.1.0
-
-* Initial release.