Support new DeprecatedInfo format for rule meta.deprecated

docs/examples/eslint-plugin-test/docs/rules/require-baz.md

@@ -1,6 +1,6 @@
 # Require using baz (`test/require-baz`)
 
-❌ This rule is deprecated. It was replaced by [`test/prefer-bar`](prefer-bar.md).
+❌ This rule has been [deprecated](https://example.com) since v1.0.0 and will be available until v2.0.0. It was replaced by [`test/prefer-bar`](prefer-bar.md) (custom message about this replacement) ([read more](https://example.com)). Custom message about overall deprecation.
 
 🚫 This rule is _disabled_ in the ⌨️ `typescript` config.
 

lib/rule-doc-notices.ts

@@ -10,18 +10,24 @@
 import { findConfigEmoji, getConfigsForRule } from './plugin-configs.js';
 import {
   RuleModule,
+  DeprecatedInfo,
   Plugin,
   ConfigsToRules,
   ConfigEmojis,
   SEVERITY_TYPE,
   NOTICE_TYPE,
   UrlRuleDocFunction,
   PathRuleDocFunction,
+  ReplacedByInfo,
 } from './types.js';
 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, replaceRulePlaceholder } from './rule-link.js';
+import {
+  getLinkToRule,
+  getMarkdownLink,
+  replaceRulePlaceholder,
+} from './rule-link.js';
 import {
   toSentenceCase,
   removeTrailingPeriod,
@@ -82,6 +88,63 @@
   return sentence;
 }
 
+function replacedByToNoticeSentence(
+  deprecated: DeprecatedInfo,
+  plugin: Plugin,
+  pluginPrefix: string,
+  pathPlugin: string,
+  pathRuleDoc: string | PathRuleDocFunction,
+  urlRuleDoc: string | UrlRuleDocFunction | undefined,
+): string | undefined {
+  if (!deprecated.replacedBy || deprecated.replacedBy.length === 0) {
+    return undefined;
+  }
+
+  function replacedByIterator(
+    info: ReplacedByInfo,
+    idx: number,
+    arr: ReplacedByInfo[],
+  ): string | undefined {
+    // A plugin maintainer should at least specify a rule name
+    if (!info.rule?.name) {
+      return undefined;
+    }
+
+    const conjunction = arr.length > 1 && idx === arr.length - 1 ? 'and ' : '';
+
+    // @todo - generate (deprecated rules)
+    // using prefix ahead of replacement rule name uses correct replacement rule link 4
+    // with nested rule names has the correct links, especially replacement rule link 5
+    // with --path-rule-doc has the correct links, especially replacement rule link 5
+    const replacementRule = info.rule.url
+      ? getMarkdownLink(info.rule.name, true, info.rule.url)
+      : getLinkToRule(
+          info.rule.name,
+          plugin,
+          pluginPrefix,
+          pathPlugin,
+          pathRuleDoc,
+          replaceRulePlaceholder(pathRuleDoc, info.rule.name),
+          true,
+          true,
+          urlRuleDoc,
+        );
+
+    const externalPlugin = info.plugin?.name && info.plugin.name !== 'eslint'
+      ? ` from ${getMarkdownLink(info.plugin.name, false, info.plugin.url)}`
+      : '';
+
+    return `${conjunction}${replacementRule}${externalPlugin}${
+      info.message ? ` (${info.message})` : ''
+    }${info.url ? ` (${getMarkdownLink('read more', false, info.url)})` : ''}`;
+  }
+
+  return `It was replaced by ${deprecated.replacedBy
+    .map((item, index, array) => replacedByIterator(item, index, array))
+    .filter(Boolean)
+    .join(', ')}.`;
+}
+
 // A few individual notices declared here just so they can be reused in multiple notices.
 const NOTICE_FIXABLE = `${EMOJI_FIXABLE} This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).`;
 const NOTICE_HAS_SUGGESTIONS = `${EMOJI_HAS_SUGGESTIONS} This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).`;
@@ -104,6 +167,7 @@
         fixable: boolean;
         hasSuggestions: boolean;
         urlConfigs?: string;
+        deprecated: boolean | DeprecatedInfo | undefined;
         replacedBy: readonly string[] | undefined;
         plugin: Plugin;
         pluginPrefix: string;
@@ -187,8 +251,8 @@
     return `${emojis.join('')} ${sentences}`;
   },
 
-  // Deprecated notice has optional "replaced by" rules list.
   [NOTICE_TYPE.DEPRECATED]: ({
+    deprecated,
     replacedBy,
     plugin,
     pluginPrefix,
@@ -197,6 +261,37 @@
     ruleName,
     urlRuleDoc,
   }) => {
+    if (typeof deprecated === 'object') {
+      const sentenceDeprecated = `${EMOJI_DEPRECATED} This rule ${
+        deprecated.deprecatedSince ? 'has been' : 'is'
+      } ${deprecated.url ? `[deprecated](${deprecated.url})` : 'deprecated'}${
+        deprecated.deprecatedSince
+          ? ` since v${deprecated.deprecatedSince}`
+          : ''
+      }${
+        deprecated.availableUntil
+          ? ` and will be available until v${deprecated.availableUntil}`
+          : ''
+      }.`;
+
+      const sentenceReplacedBy = replacedByToNoticeSentence(
+        deprecated,
+        plugin,
+        pluginPrefix,
+        pathPlugin,
+        pathRuleDoc,
+        urlRuleDoc,
+      );
+
+      const deprecatedMessage = deprecated.message
+        ? addTrailingPeriod(deprecated.message)
+        : undefined;
+
+      return [sentenceDeprecated, sentenceReplacedBy, deprecatedMessage]
+        .filter(Boolean)
+        .join(' ');
+    }
+
     const replacementRuleList = (replacedBy ?? []).map((replacementRuleName) =>
       getLinkToRule(
         replacementRuleName,
@@ -210,6 +305,7 @@
         urlRuleDoc,
       ),
     );
+
     return `${EMOJI_DEPRECATED} This rule is deprecated.${
       replacedBy && replacedBy.length > 0
         ? ` It was replaced by ${replacementRuleList.join(', ')}.`
@@ -277,7 +373,7 @@
       configsError.length > 0 ||
       configsWarn.length > 0 ||
       configsOff.length > 0,
-    [NOTICE_TYPE.DEPRECATED]: rule.meta?.deprecated || false,
+    [NOTICE_TYPE.DEPRECATED]: Boolean(rule.meta?.deprecated) || false,
     [NOTICE_TYPE.DESCRIPTION]: Boolean(rule.meta?.docs?.description) || false,
 
     // Fixable/suggestions.
@@ -359,6 +455,7 @@
     configsOff,
     ruleDocNotices,
   );
+
   let noticeType: keyof typeof notices;
 
   for (noticeType in notices) {
@@ -392,7 +489,8 @@
             fixable: Boolean(rule.meta?.fixable),
             hasSuggestions: Boolean(rule.meta?.hasSuggestions),
             urlConfigs,
-            replacedBy: rule.meta?.replacedBy,
+            deprecated: rule.meta?.deprecated,
+            replacedBy: rule.meta?.replacedBy, // eslint-disable-line @typescript-eslint/no-deprecated
             plugin,
             pluginPrefix,
             pathPlugin,

lib/rule-link.ts

@@ -79,6 +79,16 @@ export function getUrlToRule(
   );
 }
 
+export function getMarkdownLink(
+  text: string,
+  includeBackticks: boolean,
+  url?: string,
+) {
+  const displayedText = includeBackticks ? `\`${text}\`` : text;
+
+  return url ? `[${displayedText}](${url})` : displayedText;
+}
+
 /**
  * Get the markdown link (title and URL) to the rule's documentation.
  */
@@ -124,11 +134,10 @@ export function getLinkToRule(
     urlRuleDoc,
   );
 
-  const ruleNameToDisplay = `${includeBackticks ? '`' : ''}${
+  const ruleString =
     includePrefix && ruleNameWithPluginPrefix
       ? ruleNameWithPluginPrefix
-      : ruleNameWithoutPluginPrefix
-  }${includeBackticks ? '`' : ''}`;
+      : ruleNameWithoutPluginPrefix;
 
-  return urlToRule ? `[${ruleNameToDisplay}](${urlToRule})` : ruleNameToDisplay;
+  return getMarkdownLink(ruleString, includeBackticks, urlToRule);
 }

lib/types.ts

@@ -10,6 +10,10 @@ export type Rules = TSESLint.Linter.RulesRecord;
 
 export type RuleSeverity = TSESLint.Linter.RuleLevel;
 
+export type DeprecatedInfo = TSESLint.DeprecatedInfo;
+
+export type ReplacedByInfo = TSESLint.ReplacedByInfo;
+
 export type Config = TSESLint.Linter.Config;
 
 export type Plugin = TSESLint.Linter.Plugin;