feat(ts-no-empty-object-type): new rule to prevent empty objects

Author: brettz9

.README/README.md

@@ -280,6 +280,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/text-escaping": 1,
         "jsdoc/ts-prefer-function-type": 1,
         "jsdoc/ts-method-signature-style": 1,
+        "jsdoc/ts-prefer-function-type": 1,
         "jsdoc/type-formatting": 1,
         "jsdoc/valid-types": 1 // Recommended
     }

.README/rules/ts-no-empty-object-type.md

@@ -0,0 +1,24 @@
+# `ts-no-empty-object-type`
+
+Warns against use of the empty object type which, in TypeScript,
+means "any value that is defined".
+
+## Options
+
+{"gitdown": "options"}
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|true|
+|Settings||
+|Options||
+
+## Failing examples
+
+<!-- assertions-failing tsNoEmptyObjectType -->
+
+## Passing examples
+
+<!-- assertions-passing tsNoEmptyObjectType -->

README.md

@@ -307,6 +307,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/text-escaping": 1,
         "jsdoc/ts-prefer-function-type": 1,
         "jsdoc/ts-method-signature-style": 1,
+        "jsdoc/ts-prefer-function-type": 1,
         "jsdoc/type-formatting": 1,
         "jsdoc/valid-types": 1 // Recommended
     }
@@ -500,6 +501,7 @@ non-default-recommended fixer).
 |:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
 ||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
 ||:wrench:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
+|:heavy_check_mark:|| [ts-no-empty-object-type](./docs/rules/ts-no-empty-object-type.md#readme) | Warns against use of the empty object type |
 ||:wrench:| [ts-prefer-function-type](./docs/rules/ts-prefer-function-type.md#readme) | Prefers function types over call signatures when there are no other properties. |
 ||:wrench:| [type-formatting](./docs/rules/type-formatting.md#readme) | Formats JSDoc type values. |
 |:heavy_check_mark:|| [valid-types](./docs/rules/valid-types.md#readme) | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). |

docs/rules/ts-no-empty-object-type.md

@@ -0,0 +1,66 @@
+<a name="user-content-ts-no-empty-object-type"></a>
+<a name="ts-no-empty-object-type"></a>
+# <code>ts-no-empty-object-type</code>
+
+Warns against use of the empty object type which, in TypeScript,
+means "any value that is defined".
+
+<a name="user-content-ts-no-empty-object-type-options"></a>
+<a name="ts-no-empty-object-type-options"></a>
+## Options
+
+
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|``|
+|Recommended|true|
+|Settings||
+|Options||
+
+<a name="user-content-ts-no-empty-object-type-failing-examples"></a>
+<a name="ts-no-empty-object-type-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````ts
+/**
+ * @param {{}} someName
+ */
+// Message: No empty object type.
+
+/**
+ * @param {(string|{})} someName
+ */
+// Message: No empty object type.
+````
+
+
+
+<a name="user-content-ts-no-empty-object-type-passing-examples"></a>
+<a name="ts-no-empty-object-type-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````ts
+/**
+ * @param {{a: string}} someName
+ */
+
+/**
+ * @param {({a: string} & {b: number})} someName
+ */
+
+/**
+ * @param {BadType<} someName
+ */
+
+/**
+ * @param {{}} someName
+ */
+// Settings: {"jsdoc":{"mode":"jsdoc"}}
+````
+

src/index-cjs.js

@@ -67,6 +67,7 @@ import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
 import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
+import tsNoEmptyObjectType from './rules/tsNoEmptyObjectType.js';
 import tsPreferFunctionType from './rules/tsPreferFunctionType.js';
 import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
@@ -254,6 +255,7 @@ index.rules = {
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
   'ts-method-signature-style': tsMethodSignatureStyle,
+  'ts-no-empty-object-type': tsNoEmptyObjectType,
   'ts-prefer-function-type': tsPreferFunctionType,
   'type-formatting': typeFormatting,
   'valid-types': validTypes,
@@ -346,6 +348,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',
       'jsdoc/ts-method-signature-style': 'off',
+      'jsdoc/ts-no-empty-object-type': warnOrError,
       'jsdoc/ts-prefer-function-type': 'off',
       'jsdoc/type-formatting': 'off',
       'jsdoc/valid-types': warnOrError,

src/index.js

@@ -73,6 +73,7 @@ import sortTags from './rules/sortTags.js';
 import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
 import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
+import tsNoEmptyObjectType from './rules/tsNoEmptyObjectType.js';
 import tsPreferFunctionType from './rules/tsPreferFunctionType.js';
 import typeFormatting from './rules/typeFormatting.js';
 import validTypes from './rules/validTypes.js';
@@ -260,6 +261,7 @@ index.rules = {
   'tag-lines': tagLines,
   'text-escaping': textEscaping,
   'ts-method-signature-style': tsMethodSignatureStyle,
+  'ts-no-empty-object-type': tsNoEmptyObjectType,
   'ts-prefer-function-type': tsPreferFunctionType,
   'type-formatting': typeFormatting,
   'valid-types': validTypes,
@@ -352,6 +354,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/tag-lines': warnOrError,
       'jsdoc/text-escaping': 'off',
       'jsdoc/ts-method-signature-style': 'off',
+      'jsdoc/ts-no-empty-object-type': warnOrError,
       'jsdoc/ts-prefer-function-type': 'off',
       'jsdoc/type-formatting': 'off',
       'jsdoc/valid-types': warnOrError,

src/rules.d.ts

@@ -2952,6 +2952,9 @@ export interface Rules {
         }
       ];
 
+  /** Warns against use of the empty object type */
+  "jsdoc/ts-no-empty-object-type": [];
+
   /** Prefers function types over call signatures when there are no other properties. */
   "jsdoc/ts-prefer-function-type": 
     | []

src/rules/tsNoEmptyObjectType.js

@@ -0,0 +1,61 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parse as parseType,
+  traverse,
+} from '@es-joy/jsdoccomment';
+
+export default iterateJsdoc(({
+  settings,
+  utils,
+}) => {
+  if (settings.mode !== 'typescript') {
+    return;
+  }
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
+   */
+  const checkType = (tag) => {
+    const potentialType = tag.type;
+    let parsedType;
+    try {
+      parsedType = parseType(
+        /** @type {string} */ (potentialType), 'typescript',
+      );
+    } catch {
+      return;
+    }
+
+    traverse(parsedType, (nde) => {
+      switch (nde.type) {
+        case 'JsdocTypeObject': {
+          if (!nde.elements.length) {
+            utils.reportJSDoc('No empty object type.', tag);
+          }
+        }
+      }
+    });
+  };
+
+  const tags = utils.filterTags(({
+    tag,
+  }) => {
+    return Boolean(tag !== 'import' && utils.tagMightHaveTypePosition(tag));
+  });
+
+  for (const tag of tags) {
+    if (tag.type) {
+      checkType(tag);
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Warns against use of the empty object type',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/ts-no-empty-object-type.md#repos-sticky-header',
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+});

test/rules/assertions/tsNoEmptyObjectType.js

@@ -0,0 +1,65 @@
+export default {
+  invalid: [
+    {
+      code: `
+        /**
+         * @param {{}} someName
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'No empty object type.',
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         * @param {(string|{})} someName
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'No empty object type.',
+        },
+      ],
+    },
+  ],
+  valid: [
+    {
+      code: `
+        /**
+         * @param {{a: string}} someName
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {({a: string} & {b: number})} someName
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {BadType<} someName
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @param {{}} someName
+         */
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'jsdoc',
+        },
+      },
+    },
+  ],
+};

test/rules/ruleNames.json

@@ -68,6 +68,7 @@
   "tag-lines",
   "text-escaping",
   "ts-method-signature-style",
+  "ts-no-empty-object-type",
   "ts-prefer-function-type",
   "type-formatting",
   "valid-types"