Adding a used-types rule

.README/README.md

@@ -57,6 +57,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/empty-tags": 1, // Recommended
         "jsdoc/implements-on-classes": 1, // Recommended
         "jsdoc/informative-docs": 1,
+        "jsdoc/mark-used": 1,
         "jsdoc/match-description": 1,
         "jsdoc/multiline-blocks": 1, // Recommended
         "jsdoc/no-bad-blocks": 1,
@@ -203,6 +204,7 @@ Problems reported by rules which have a wrench :wrench: below can be fixed autom
 |:heavy_check_mark:|:wrench:|[empty-tags](./docs/rules/empty-tags.md#readme)|Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content|
 |:heavy_check_mark:||[implements-on-classes](./docs/rules/implements-on-classes.md#readme)|Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors)|
 |||[informative-docs](./docs/rules/informative-docs.md#readme)|Reports on JSDoc texts that serve only to restart their attached name.|
+|||[mark-used](./docs/rules/mark-used.md#readme)|Marks all types referenced in `{@link}`d tags as used.|
 |||[match-description](./docs/rules/match-description.md#readme)|Defines customizable regular expression rules for your tag descriptions|
 ||:wrench:|[match-name](./docs/rules/match-name.md#readme)|Reports the name portion of a JSDoc tag if matching or not matching a given regular expression|
 |:heavy_check_mark:|:wrench:|[multiline-blocks](./docs/rules/multiline-blocks.md#readme)|Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks|

.README/rules/mark-used.md

@@ -0,0 +1,27 @@
+# `mark-used`
+
+{"gitdown": "contents", "rootId": "mark-used"}
+
+Marks all types referenced in `{@link}` tags as used.
+
+## Fixer
+
+Not applicable.
+
+#### Options
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|N/A|
+|Recommended|false|
+|Settings||
+|Options||
+
+## Failing examples
+
+<!-- assertions-failing markUsed -->
+
+## Passing examples
+
+<!-- assertions-passing markUsed -->

README.md

@@ -70,6 +70,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/empty-tags": 1, // Recommended
         "jsdoc/implements-on-classes": 1, // Recommended
         "jsdoc/informative-docs": 1,
+        "jsdoc/mark-used": 1,
         "jsdoc/match-description": 1,
         "jsdoc/multiline-blocks": 1, // Recommended
         "jsdoc/no-bad-blocks": 1,
@@ -224,6 +225,7 @@ Problems reported by rules which have a wrench :wrench: below can be fixed autom
 |:heavy_check_mark:|:wrench:|[empty-tags](./docs/rules/empty-tags.md#readme)|Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content|
 |:heavy_check_mark:||[implements-on-classes](./docs/rules/implements-on-classes.md#readme)|Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors)|
 |||[informative-docs](./docs/rules/informative-docs.md#readme)|Reports on JSDoc texts that serve only to restart their attached name.|
+|||[mark-used](./docs/rules/mark-used.md#readme)|Marks all types referenced in `{@link}`d tags as used.|
 |||[match-description](./docs/rules/match-description.md#readme)|Defines customizable regular expression rules for your tag descriptions|
 ||:wrench:|[match-name](./docs/rules/match-name.md#readme)|Reports the name portion of a JSDoc tag if matching or not matching a given regular expression|
 |:heavy_check_mark:|:wrench:|[multiline-blocks](./docs/rules/multiline-blocks.md#readme)|Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks|

docs/rules/mark-used.md

@@ -0,0 +1,66 @@
+<a name="user-content-mark-used"></a>
+<a name="mark-used"></a>
+# <code>mark-used</code>
+
+* [Fixer](#user-content-mark-used-fixer)
+* [Failing examples](#user-content-mark-used-failing-examples)
+* [Passing examples](#user-content-mark-used-passing-examples)
+
+
+Marks all types referenced in `{@link}` tags as used.
+
+<a name="user-content-mark-used-fixer"></a>
+<a name="mark-used-fixer"></a>
+## Fixer
+
+Not applicable.
+
+<a name="user-content-mark-used-fixer-options"></a>
+<a name="mark-used-fixer-options"></a>
+#### Options
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|N/A|
+|Recommended|false|
+|Settings||
+|Options||
+
+<a name="user-content-mark-used-failing-examples"></a>
+<a name="mark-used-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````js
+
+````
+
+
+
+<a name="user-content-mark-used-passing-examples"></a>
+<a name="mark-used-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+class Foo {}
+/** @param {Foo} */
+function foo() {}
+foo();
+
+class Foo {}
+/** @returns {Foo} */
+function foo() {}
+foo();
+
+class Foo {}
+class Bar {}
+class Baz {}
+class Qux {}
+/** @type {(!Foo|?Bar|...Baz|Qux[]|foo=)} */
+let foo = null;
+````
+

src/index.js

@@ -12,6 +12,7 @@ import checkValues from './rules/checkValues';
 import emptyTags from './rules/emptyTags';
 import implementsOnClasses from './rules/implementsOnClasses';
 import informativeDocs from './rules/informativeDocs';
+import markUsed from './rules/markUsed';
 import matchDescription from './rules/matchDescription';
 import matchName from './rules/matchName';
 import multilineBlocks from './rules/multilineBlocks';
@@ -68,6 +69,7 @@ const index = {
     'empty-tags': emptyTags,
     'implements-on-classes': implementsOnClasses,
     'informative-docs': informativeDocs,
+    'mark-used': markUsed,
     'match-description': matchDescription,
     'match-name': matchName,
     'multiline-blocks': multilineBlocks,

src/rules/markUsed.js

@@ -0,0 +1,59 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+/**
+ * Extracts the type names from a type declaration string.
+ *
+ * @see https://jsdoc.app/tags-type.html
+ */
+const extractTypeNames = (type) => {
+  if (type.startsWith('(') && type.endsWith(')')) {
+    // Type union
+    return type.slice(1, type.length - 1).split('|').flatMap(extractTypeNames);
+  } else if (type.endsWith('[]')) {
+    // Arrays
+    return extractTypeNames(type.slice(0, Math.max(0, type.length - 2)));
+  } else if (type.startsWith('!') || type.startsWith('?')) {
+    // Nullable type or non-nullable type
+    return extractTypeNames(type.slice(1));
+  } else if (type.startsWith('...')) {
+    // Variable number of that type
+    return extractTypeNames(type.slice(3));
+  } else if (type.endsWith('=')) {
+    // Optional parameter
+    return extractTypeNames(type.slice(0, Math.max(0, type.length - 1)));
+  } else {
+    return [
+      type,
+    ];
+  }
+};
+
+export default iterateJsdoc(({
+  jsdoc,
+  jsdocNode,
+  context,
+}) => {
+  const sourceCode = context.getSourceCode();
+  for (const tag of jsdoc.tags) {
+    const typeNames = extractTypeNames(tag.type);
+    for (const typeName of typeNames) {
+      sourceCode.markVariableAsUsed(typeName, jsdocNode);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Marks all types referenced in {@link} tags as used',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-mark-used',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {},
+      },
+    ],
+    type: 'suggestion',
+  },
+});

test/rules/assertions/markUsed.js

@@ -0,0 +1,51 @@
+export default {
+  invalid: [],
+  valid: [
+    // {
+    //   code: `
+    //     const foo = "bar";
+    //     /** This thing uses {@link foo} for something */
+    //   `,
+    //   /*
+    //   rules: {
+    //     'no-unused-vars': 'error',
+    //   },
+    //   */
+    // },
+    {
+      code: `
+        class Foo {}
+        /** @param {Foo} */
+        function foo() {}
+        foo();
+      `,
+      rules: {
+        'no-unused-vars': 'error',
+      },
+    },
+    {
+      code: `
+        class Foo {}
+        /** @returns {Foo} */
+        function foo() {}
+        foo();
+      `,
+      rules: {
+        'no-unused-vars': 'error',
+      },
+    },
+    {
+      code: `
+        class Foo {}
+        class Bar {}
+        class Baz {}
+        class Qux {}
+        /** @type {(!Foo|?Bar|...Baz|Qux[]|foo=)} */
+        let foo = null;
+      `,
+      rules: {
+        'no-unused-vars': 'error',
+      },
+    },
+  ],
+};

test/rules/ruleNames.json

@@ -13,6 +13,7 @@
   "empty-tags",
   "implements-on-classes",
   "informative-docs",
+  "mark-used",
   "match-description",
   "match-name",
   "multiline-blocks",