Add rule doc notice type for rule description (#350)

README.md

@@ -157,7 +157,7 @@ These are the types of rule metadata that are available for display in rule list
 | ⚠️ | `configsWarn` | Yes | No | Whether a rule is set to `warn` in a config. |
 | 💼 | `configs` | No | Yes | What configs set a rule to what [severities](https://eslint.org/docs/latest/user-guide/configuring/rules#rule-severities). |
 | ❌ | `deprecated`  | Yes | Yes | Whether a rule is deprecated (i.e. likely to be removed/renamed in a future major version). |
-| | `description`  | Yes | No | The rule description. |
+| | `description`  | Yes | Yes | The rule description. |
 | 🔧💡 | `fixableAndHasSuggestions` | Yes | Yes | Whether a rule is [fixable](https://eslint.org/docs/latest/developer-guide/working-with-rules#applying-fixes) and/or has [suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions). |
 | 🔧 | `fixable` | Yes | Yes | Whether a rule is [fixable](https://eslint.org/docs/latest/developer-guide/working-with-rules#applying-fixes). |
 | 💡 | `hasSuggestions` | Yes | Yes | Whether a rule has [suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions). |

lib/options.ts

@@ -34,6 +34,7 @@ export const NOTICE_TYPE_DEFAULT_PRESENCE_AND_ORDERING: {
   [NOTICE_TYPE.OPTIONS]: false,
   [NOTICE_TYPE.REQUIRES_TYPE_CHECKING]: true,
   [NOTICE_TYPE.TYPE]: false,
+  [NOTICE_TYPE.DESCRIPTION]: false,
 };
 
 const DEFAULT_RULE_DOC_TITLE_FORMAT: RuleDocTitleFormat =

lib/rule-doc-notices.ts

@@ -20,7 +20,11 @@ import { RULE_TYPE, RULE_TYPE_MESSAGES_NOTICES } from './rule-type.js';
 import { RuleDocTitleFormat } from './rule-doc-title-format.js';
 import { hasOptions } from './rule-options.js';
 import { getLinkToRule, getUrlToRule } from './rule-link.js';
-import { toSentenceCase, removeTrailingPeriod } from './string.js';
+import {
+  toSentenceCase,
+  removeTrailingPeriod,
+  addTrailingPeriod,
+} from './string.js';
 
 function severityToTerminology(severity: SEVERITY_TYPE) {
   switch (severity) {
@@ -79,6 +83,7 @@ const RULE_NOTICES: {
         configsWarn: readonly string[];
         configsOff: readonly string[];
         configEmojis: ConfigEmojis;
+        description?: string;
         fixable: boolean;
         hasSuggestions: boolean;
         urlConfigs?: string;
@@ -192,6 +197,17 @@ const RULE_NOTICES: {
     }`;
   },
 
+  [NOTICE_TYPE.DESCRIPTION]: ({ description }) => {
+    /* istanbul ignore next -- this shouldn't happen */
+    if (!description) {
+      throw new Error(
+        'Should not be trying to display description notice for rule with no description.'
+      );
+    }
+    // Return the description like a normal body sentence.
+    return addTrailingPeriod(toSentenceCase(description));
+  },
+
   [NOTICE_TYPE.TYPE]: ({ type }) => {
     /* istanbul ignore next -- this shouldn't happen */
     if (!type) {
@@ -242,6 +258,7 @@ function getNoticesForRule(
       configsWarn.length > 0 ||
       configsOff.length > 0,
     [NOTICE_TYPE.DEPRECATED]: rule.meta?.deprecated || false,
+    [NOTICE_TYPE.DESCRIPTION]: Boolean(rule.meta?.docs?.description) || false,
 
     // Fixable/suggestions.
     [NOTICE_TYPE.FIXABLE]: Boolean(rule.meta?.fixable),
@@ -348,6 +365,7 @@ function getRuleNoticeLines(
             configsWarn,
             configsOff,
             configEmojis,
+            description: rule.meta?.docs?.description,
             fixable: Boolean(rule.meta?.fixable),
             hasSuggestions: Boolean(rule.meta?.hasSuggestions),
             urlConfigs,

lib/string.ts

@@ -12,6 +12,10 @@ export function removeTrailingPeriod(str: string) {
   return str.replace(/\.$/u, '');
 }
 
+export function addTrailingPeriod(str: string) {
+  return str.replace(/\.?$/u, '.');
+}
+
 /**
  * Example: FOO => Foo, foo => Foo
  */

lib/types.ts

@@ -58,6 +58,7 @@ export type ConfigEmojis = readonly { config: string; emoji: string }[];
 export enum NOTICE_TYPE {
   CONFIGS = 'configs',
   DEPRECATED = 'deprecated',
+  DESCRIPTION = 'description',
   FIXABLE = 'fixable',
   FIXABLE_AND_HAS_SUGGESTIONS = 'fixableAndHasSuggestions', // Consolidated notice for space-saving.
   HAS_SUGGESTIONS = 'hasSuggestions',

test/lib/generate/__snapshots__/option-rule-doc-notices-test.ts.snap

@@ -25,6 +25,8 @@ exports[`generate (--rule-doc-notices) basic shows the right rule doc notices 2`
 
 ❌ This rule is deprecated.
 
+Description for no-foo.
+
 ❗ This rule identifies problems that could cause errors or unexpected behavior.
 
 <!-- end auto-generated rule header -->

test/lib/generate/option-rule-doc-notices-test.ts

@@ -56,8 +56,9 @@ describe('generate (--rule-doc-notices)', function () {
           NOTICE_TYPE.HAS_SUGGESTIONS,
           NOTICE_TYPE.FIXABLE,
           NOTICE_TYPE.DEPRECATED,
+          NOTICE_TYPE.DESCRIPTION,
           NOTICE_TYPE.TYPE,
-        ], // Random values including an optional notice.
+        ], // Random values including all the optional notices.
       });
       expect(readFileSync('README.md', 'utf8')).toMatchSnapshot();
       expect(readFileSync('docs/rules/no-foo.md', 'utf8')).toMatchSnapshot();

test/lib/string-test.ts

@@ -0,0 +1,37 @@
+import {
+  addTrailingPeriod,
+  removeTrailingPeriod,
+  toSentenceCase,
+} from '../../lib/string.js';
+
+describe('strings', function () {
+  describe('#addTrailingPeriod', function () {
+    it('handles when already has period', function () {
+      expect(addTrailingPeriod('foo.')).toStrictEqual('foo.');
+    });
+
+    it('handles when does not have period', function () {
+      expect(addTrailingPeriod('foo')).toStrictEqual('foo.');
+    });
+  });
+
+  describe('#removeTrailingPeriod', function () {
+    it('handles when already has period', function () {
+      expect(removeTrailingPeriod('foo.')).toStrictEqual('foo');
+    });
+
+    it('handles when does not have period', function () {
+      expect(removeTrailingPeriod('foo')).toStrictEqual('foo');
+    });
+  });
+
+  describe('#toSentenceCase', function () {
+    it('handles when lowercase first letter', function () {
+      expect(toSentenceCase('hello world')).toStrictEqual('Hello world');
+    });
+
+    it('handles when uppercase first letter', function () {
+      expect(toSentenceCase('Hello World')).toStrictEqual('Hello World');
+    });
+  });
+});