eslint-docgen 0.4.5 → 0.6.2

package/README.md

@@ -63,7 +63,7 @@ To migrate an existing plugin with manually built documentation you can use the
 
 ## ⚙️ Configuration
 
-Create a JSON/JavaScript file called `.eslintdocgenrc.json`/`.eslintdocgenrc.js` in your project root:
+Configuration for all rules in a project is controlled by creating a JSON/JavaScript file called `.eslintdocgenrc.json`/`.eslintdocgenrc.js` in your project root:
 
 #### JSON
 ```jsonc
@@ -81,6 +81,12 @@ module.exports = {
 };
 ```
 
+#### Overriding
+
+The project-wide rules configuration can be overridden for individual rules by adding a `docgenConfig` property to the tests object passed to RuleTester.run(). All configuration options that are supported project-wide can be changed.
+
+### Options
+
 The following config options are available:
 
 #### `docPath` (*required*)
@@ -123,6 +129,9 @@ Shows config comments at the top of code examples:
 #### `showFixExamples` (default `true`)
 Show examples of how code is fixed by the rule.
 
+#### `showFilenames` (default: `false`)
+Show the relevant file name for test cases.
+
 #### `excludeExamplesByDefault` (default `false`)
 Exclude tests from being used as examples by default. When this is `true` users must set `docgen: true` on any test they want to be included in examples.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eslint-docgen",
-	"version": "0.4.5",
+	"version": "0.6.2",
 	"description": "Automatically generate ESLint plugin documentation from rule metadata and test cases.",
 	"repository": {
 		"type": "git",
@@ -20,10 +20,10 @@
 		"report": "nyc report --reporter=html"
 	},
 	"engines": {
-		"node": ">=10.0.0"
+		"node": ">=12.0.0"
 	},
 	"dependencies": {
-		"chalk": "^4.1.0",
+		"chalk": "^4.1.2",
 		"ejs": "^3.1.6",
 		"eslint": ">=5.0.0",
 		"import-fresh": "^3.3.0",
@@ -36,9 +36,9 @@
 		"upath": "^2.0.1"
 	},
 	"devDependencies": {
-		"eslint-config-wikimedia": "^0.19.0",
+		"eslint-config-wikimedia": "^0.21.0",
 		"eslint-plugin-node": "^11.1.0",
-		"mocha": "^8.3.2",
+		"mocha": "^9.1.3",
 		"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
@@ -59,7 +66,25 @@ function buildDocsFromTests(
 		return typeof test === 'string' ? test : test.code;
 	}
 
-	function buildRuleDetails( testList, valid, showFixes ) {
+	/**
+	 * @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 no file name is set
+			return null;
+		}
+		return path.basename( test.filename );
+	}
+
+	function buildRuleDetails( testList, isValid, showFixes ) {
+		testList = testList.filter( ( test ) =>
+			test.docgen === undefined ?
+				!config.excludeExamplesByDefault :
+				test.docgen
+		);
+
 		let fixedCode, fixedOutput, maxCodeLength;
 		const testsByOptions = {};
 
@@ -96,30 +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;
-			if ( test.options || test.settings ) {
-				optionsAndSettings = {
-					options: test.options,
-					settings: test.settings
-				};
-			}
-			const hash = optionsAndSettings ? JSON.stringify( optionsAndSettings ) : '';
+			const hash = JSON.stringify( hashObject );
 
 			codeSet[ hash ] = codeSet[ hash ] || {};
 
@@ -144,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++ ) {
@@ -164,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 );
@@ -190,10 +222,12 @@ function buildDocsFromTests(
 		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';
 			}
@@ -202,9 +236,10 @@ function buildDocsFromTests(
 
 			return {
 				key: key,
-				valid: valid,
+				valid: isValid,
 				options: options ? JSON.stringify( options ) : '',
 				settings: settings ? JSON.stringify( settings ) : '',
+				filename: filename || '',
 				examples: examples,
 				testCount: section.tests.length
 			};

package/src/config-schema.json

@@ -5,6 +5,7 @@
 		"fixCodeExamples": { "type": "boolean" },
 		"showConfigComments": { "type": "boolean" },
 		"showFixExamples": { "type": "boolean" },
+		"showFilenames": { "type": "boolean" },
 		"tabWidth": {
 			"type": "integer",
 			"minimum": 0

package/src/default-config.js

@@ -9,6 +9,7 @@ module.exports = {
 	pluginName: pluginName,
 	fixCodeExamples: true,
 	showConfigComments: false,
+	showFilenames: false,
 	showFixExamples: true,
 	tabWidth: 4,
 	docPath: null,

package/src/rule-tester.js

@@ -3,37 +3,32 @@
 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 top level property "noDoc", used in documentation building mode
+			// 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"
+			// (used in documentation building mode).
+			delete tests.docgenConfig;
+
 			return super.run.call( this, name, rule, tests );
 		}
 	}

package/src/templates/inConfig.ejs

@@ -1 +1 @@
-⚙️ This rule is enabled in `plugin:<%- pluginName %>/<%- inConfig.config %>`<%- include( 'optionsAndSettings', { data: inConfig } ) %>.
+📋 This rule is enabled in `plugin:<%- pluginName %>/<%- inConfig.config %>`<%- include( 'optionsAndSettings', { data: inConfig } ) %>.

package/src/templates/index.ejs

@@ -1,3 +1,5 @@
+[//]: # (This file is generated by eslint-docgen. Do not edit it directly.)
+
 # <%- title %>
 
 <%- description %>

package/src/templates/optionsAndSettings.ejs

@@ -1,4 +1,6 @@
 <% if ( data.options || data.settings ) { _%>
  with<% if ( data.options ) { %> `<%- data.options %>` options<% } _%>
 <% if ( data.settings ) { %><% if ( data.options ) { %> and<% } %> `<%- data.settings %>` settings<% } _%>
-<% } %>
+<% } _%>
+<% if ( data.filename ) { _%>
+ for a file named `<%- data.filename %>`<% } %>

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,21 +13,19 @@ 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 configErrors = require( './validate-config' )( config );
-
-if ( configErrors.length ) {
-	console.log( formatter.heading( configPath ) );
-	configErrors.forEach( ( error ) => console.log( formatter.error( error ) ) );
-	console.log();
-	process.exit( 1 );
+const configValidator = require( './validate-config' );
+function assertValidConfig( maybeValidConfig, configSource ) {
+	const configErrors = configValidator( 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' );
@@ -39,28 +36,27 @@ if ( config.globalTemplatePath ) {
 const { globalTemplates, loadRuleTemplate } = loadTemplates( templatePaths );
 
 function writeDocsFromTests( name, rule, tests, testerConfig, done ) {
-	const outputPath = packagePath( config.docPath.replace( '{name}', name ) );
+	// If the tests have a `docgenConfig` property, this overrides the global configuration
+	let configForRule = config;
+	if ( tests.docgenConfig !== undefined ) {
+		configForRule = Object.assign( {}, config, tests.docgenConfig );
+		assertValidConfig( configForRule, 'Rule specific config for ' + name );
+		delete tests.docgenConfig;
+	}
+	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(
-			name, rule.meta, tests, configMap, config,
+			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 );
@@ -81,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,78 +0,0 @@
-# eslint-docgen release history
-
-## 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.