Added -flavor rulesets, added contents- rulesets, and expanded rules …

…as suggested
gajus · Aug 12, 2024 · 8506706 · 8506706
1 parent ab45c35
commit 8506706
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 27 deletions.
diff --git a/.README/README.md b/.README/README.md
@@ -62,21 +62,36 @@ The general starting rulesets you can extend from in flat config are:
 #### Granular Flat Configs
 
 There also exist several more granular, standalone TypeScript rulesets you can extend from.
-These each only enable a subset of the recommended starting rules:
-
-* `jsdoc.configs['flat/logical-typescript']`: Includes only the rules that enforce proper tag values
-  * `jsdoc.configs['flat/logical-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-* `jsdoc.configs['flat/requirements-typescript']`: Includes only the rules that enforce tags exist
-  * `jsdoc.configs['flat/requirements-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-* `jsdoc.configs['flat/stylistic-typescript']`: Includes only the rules that enforce clear, consistent tag formatting and styles
-  * `jsdoc.configs['flat/stylistic-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-
-For example, to enforce only that any JSDoc tags are valid and styled consistently, without enforcing that they must always exist:
+These each only enable mostly or only rules from the recommended starting rules:
+
+* **Contents**: rules that check names and descriptions
+  * `jsdoc.configs['flat/contents-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/contents-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/contents-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/contents-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Logical**: rules that enforce proper tag values
+  * `jsdoc.configs['flat/logical-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/logical-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Requirements**: rules that enforce tags exist
+  * `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/requirements-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Stylistic**: rules that enforce clear, consistent tag formatting and styles
+  * `jsdoc.configs['flat/stylistic-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/stylistic-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/stylistic-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/stylistic-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+
+For example, to enforce only that any JSDoc tags and their contents are valid and styled consistently in TypeScript files, without enforcing that tags must always exist:
 
 ```js
 import jsdoc from 'eslint-plugin-jsdoc';
 
 export default [
+  jsdoc.configs['flat/contents-typescript-error'],
   jsdoc.configs['flat/logical-typescript-error'],
   jsdoc.configs['flat/stylistic-typescript-error'],
 ];

diff --git a/README.md b/README.md
@@ -82,21 +82,36 @@ The general starting rulesets you can extend from in flat config are:
 #### Granular Flat Configs
 
 There also exist several more granular, standalone TypeScript rulesets you can extend from.
-These each only enable a subset of the recommended starting rules:
-
-* `jsdoc.configs['flat/logical-typescript']`: Includes only the rules that enforce proper tag values
-  * `jsdoc.configs['flat/logical-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-* `jsdoc.configs['flat/requirements-typescript']`: Includes only the rules that enforce tags exist
-  * `jsdoc.configs['flat/requirements-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-* `jsdoc.configs['flat/stylistic-typescript']`: Includes only the rules that enforce clear, consistent tag formatting and styles
-  * `jsdoc.configs['flat/stylistic-typescript-error']`: The same, reporting with failing errors instead of mere warnings
-
-For example, to enforce only that any JSDoc tags are valid and styled consistently, without enforcing that they must always exist:
+These each only enable mostly or only rules from the recommended starting rules:
+
+* **Contents**: rules that check names and descriptions
+  * `jsdoc.configs['flat/contents-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/contents-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/contents-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/contents-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Logical**: rules that enforce proper tag values
+  * `jsdoc.configs['flat/logical-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/logical-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Requirements**: rules that enforce tags exist
+  * `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/requirements-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+* **Stylistic**: rules that enforce clear, consistent tag formatting and styles
+  * `jsdoc.configs['flat/stylistic-typescript']`: for TypeScript files, with reports set to warn
+  * `jsdoc.configs['flat/stylistic-typescript-error']`: for TypeScript files, with reports set to error
+  * `jsdoc.configs['flat/stylistic-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
+  * `jsdoc.configs['flat/stylistic-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
+
+For example, to enforce only that any JSDoc tags and their contents are valid and styled consistently in TypeScript files, without enforcing that tags must always exist:
 
 ```js
 import jsdoc from 'eslint-plugin-jsdoc';
 
 export default [
+  jsdoc.configs['flat/contents-typescript-error'],
   jsdoc.configs['flat/logical-typescript-error'],
   jsdoc.configs['flat/stylistic-typescript-error'],
 ];

diff --git a/src/index.js b/src/index.js
@@ -261,7 +261,7 @@ const createRecommendedTypeScriptFlavorRuleset = (warnOrError, flatName) => {
 };
 
 /**
- * @param {string[]} ruleNames
+ * @param {(string | unknown[])[]} ruleNames
  */
 const createStandaloneRulesetFactory = (ruleNames) => {
   /**
@@ -273,15 +273,36 @@ const createStandaloneRulesetFactory = (ruleNames) => {
     return {
       name: 'jsdoc/' + flatName,
       plugins: { jsdoc: index },
-      rules: Object.fromEntries(ruleNames.map(ruleName => [ruleName, warnOrError])),
+      rules: Object.fromEntries(
+        ruleNames.map(
+          ruleName =>
+            typeof ruleName === "string"
+              ? [ruleName, warnOrError]
+              : [ruleName[0], warnOrError, ...ruleName.slice(1)]
+        )
+      ),
     };
   };
 }
 
-const createLogicalTypescriptRuleset = createStandaloneRulesetFactory([
+const contentsRules = [
+  'jsdoc/informative-docs',
+  'jsdoc/match-description',
+  'jsdoc/match-name',
+  'jsdoc/no-blank-block-descriptions',
+  'jsdoc/no-blank-blocks',
+  ['jsdoc/text-escaping', { escapeHTML: true }]
+]
+
+const createContentsTypescriptRuleset = createStandaloneRulesetFactory(contentsRules);
+
+const createContentsTypescriptFlavorRuleset = createStandaloneRulesetFactory(contentsRules);
+
+const logicalRules = [
   'jsdoc/check-access',
   'jsdoc/check-param-names',
   'jsdoc/check-property-names',
+  'jsdoc/check-syntax',
   'jsdoc/check-tag-names',
   'jsdoc/check-template-names',
   'jsdoc/check-types',
@@ -290,13 +311,18 @@ const createLogicalTypescriptRuleset = createStandaloneRulesetFactory([
   'jsdoc/implements-on-classes',
   'jsdoc/require-returns-check',
   'jsdoc/require-yields-check',
+  'jsdoc/no-bad-blocks',
   'jsdoc/no-defaults',
   'jsdoc/no-types',
   'jsdoc/no-undefined-types',
   'jsdoc/valid-types',
-]);
+];
+
+const createLogicalTypescriptRuleset = createStandaloneRulesetFactory(logicalRules);
+
+const createLogicalTypescriptFlavorRuleset = createStandaloneRulesetFactory(logicalRules);
 
-const createRequirementsTypeScriptRuleset = createStandaloneRulesetFactory([
+const requirementsRules = [
   'jsdoc/require-example',
   'jsdoc/require-jsdoc',
   'jsdoc/require-param',
@@ -308,15 +334,32 @@ const createRequirementsTypeScriptRuleset = createStandaloneRulesetFactory([
   'jsdoc/require-returns',
   'jsdoc/require-returns-description',
   'jsdoc/require-yields',
+];
+
+const createRequirementsTypeScriptRuleset = createStandaloneRulesetFactory(requirementsRules);
+
+const createRequirementsTypeScriptFlavorRuleset = createStandaloneRulesetFactory([
+  ...requirementsRules,
+  'jsdoc/require-param-type',
+  'jsdoc/require-property-type',
+  'jsdoc/require-returns-type',
+  'jsdoc/require-template',
 ]);
 
-const createStylisticTypeScriptRuleset = createStandaloneRulesetFactory([
+const stylisticRules = [
   'jsdoc/check-alignment',
+  'jsdoc/check-line-alignment',
   'jsdoc/lines-before-block',
   'jsdoc/multiline-blocks',
   'jsdoc/no-multi-asterisks',
+  'jsdoc/require-asterisk-prefix',
+  ['jsdoc/require-hyphen-before-param-description', 'never'],
   'jsdoc/tag-lines',
-]);
+];
+
+const createStylisticTypeScriptRuleset = createStandaloneRulesetFactory(stylisticRules);
+
+const createStylisticTypeScriptFlavorRuleset = createStandaloneRulesetFactory(stylisticRules);
 
 /* c8 ignore next 3 -- TS */
 if (!index.configs) {
@@ -337,12 +380,22 @@ index.configs['flat/recommended-typescript-error'] = createRecommendedTypeScript
 index.configs['flat/recommended-typescript-flavor'] = createRecommendedTypeScriptFlavorRuleset('warn', 'flat/recommended-typescript-flavor');
 index.configs['flat/recommended-typescript-flavor-error'] = createRecommendedTypeScriptFlavorRuleset('error', 'flat/recommended-typescript-flavor-error');
 
+index.configs['flat/contents-typescript'] = createContentsTypescriptRuleset('warn', 'flat/contents-typescript');
+index.configs['flat/contents-typescript-error'] = createContentsTypescriptRuleset('error', 'flat/contents-typescript-error');
+index.configs['flat/contents-typescript-flavor'] = createContentsTypescriptFlavorRuleset('warn', 'flat/contents-typescript-flavor');
+index.configs['flat/contents-typescript-flavor-error'] = createContentsTypescriptFlavorRuleset('error', 'flat/contents-typescript-error-flavor');
 index.configs['flat/logical-typescript'] = createLogicalTypescriptRuleset('warn', 'flat/logical-typescript');
 index.configs['flat/logical-typescript-error'] = createLogicalTypescriptRuleset('error', 'flat/logical-typescript-error');
+index.configs['flat/logical-typescript-flavor'] = createLogicalTypescriptFlavorRuleset('warn', 'flat/logical-typescript-flavor');
+index.configs['flat/logical-typescript-flavor-error'] = createLogicalTypescriptFlavorRuleset('error', 'flat/logical-typescript-error-flavor');
 index.configs['flat/requirements-typescript'] = createRequirementsTypeScriptRuleset('warn', 'flat/requirements-typescript');
 index.configs['flat/requirements-typescript-error'] = createRequirementsTypeScriptRuleset('error', 'flat/requirements-typescript-error');
+index.configs['flat/requirements-typescript-flavor'] = createRequirementsTypeScriptFlavorRuleset('warn', 'flat/requirements-typescript-flavor');
+index.configs['flat/requirements-typescript-flavor-error'] = createRequirementsTypeScriptFlavorRuleset('error', 'flat/requirements-typescript-error-flavor');
 index.configs['flat/stylistic-typescript'] = createStylisticTypeScriptRuleset('warn', 'flat/stylistic-typescript');
 index.configs['flat/stylistic-typescript-error'] = createStylisticTypeScriptRuleset('error', 'flat/stylistic-typescript-error');
+index.configs['flat/stylistic-typescript-flavor'] = createStylisticTypeScriptFlavorRuleset('warn', 'flat/stylistic-typescript-flavor');
+index.configs['flat/stylistic-typescript-flavor-error'] = createStylisticTypeScriptFlavorRuleset('error', 'flat/stylistic-typescript-error-flavor');
 
 index.configs.examples = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
   {