fix(check-tag-names, empty-tags, sort-tags, valid-types): support new TypeScript overload and satisfies; fixes #1045

Author: brettz9

README.md

@@ -55,6 +55,7 @@ const defaultTagOrder = [
 
       // TypeScript
       'internal',
+      'overload',
 
       'const',
       'constant',
@@ -101,6 +102,9 @@ const defaultTagOrder = [
       'listens',
       'this',
 
+      // TypeScript
+      'satisfies',
+
       // Access
       'static',
       'private',

src/defaultTagOrder.js

@@ -756,6 +756,15 @@ const getDefaultTagStructureForMode = (mode) => {
       ]),
     ],
 
+    [
+      'satisfies', new Map([
+        // Shows curly brackets in the doc signature and examples
+        [
+          'typeRequired', true,
+        ],
+      ]),
+    ],
+
     [
       'see', new Map([
         // Signature allows for "namepath" or text, so user must configure to

src/getDefaultTagStructureForMode.js

@@ -10,6 +10,7 @@ const defaultEmptyTags = new Set([
 
   // jsdoc doesn't use but allow for TypeScript
   'internal',
+  'overload',
 ]);
 
 const emptyIfNotClosure = new Set([

src/rules/emptyTags.js

@@ -124,6 +124,12 @@ const typeScriptTags = {
   // https://www.typescriptlang.org/tsconfig/#stripInternal
   internal: [],
 
+  // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#overload-support-in-jsdoc
+  overload: [],
+
+  // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#satisfies-support-in-jsdoc
+  satisfies: [],
+
   // `@template` is also in TypeScript per:
   //      https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
   template: [],
@@ -150,6 +156,8 @@ const {
   /* eslint-disable no-unused-vars */
   inheritdoc,
   internal,
+  overload,
+  satisfies,
 
   // Will be inverted to prefer `return`
   returns,

src/tagNames.js

@@ -842,9 +842,17 @@ export default {
       code: `${ALL_TYPESCRIPT_TAGS_COMMENT}\nfunction quux (foo) {}`,
       errors: [
         {
-          line: lineCount(ALL_TYPESCRIPT_TAGS_COMMENT) - 1,
+          line: lineCount(ALL_TYPESCRIPT_TAGS_COMMENT) - 3,
           message: 'Invalid JSDoc tag name "internal".',
         },
+        {
+          line: lineCount(ALL_TYPESCRIPT_TAGS_COMMENT) - 2,
+          message: 'Invalid JSDoc tag name "overload".',
+        },
+        {
+          line: lineCount(ALL_TYPESCRIPT_TAGS_COMMENT) - 1,
+          message: 'Invalid JSDoc tag name "satisfies".',
+        },
         {
           line: lineCount(ALL_TYPESCRIPT_TAGS_COMMENT),
           message: 'Invalid JSDoc tag name "template".',
@@ -1289,7 +1297,7 @@ export default {
            * Converts the images specified by the indices to base64 synchronously.
            * @function WebTwain#ConvertToBase64
            * @returns {Base64Result}
-       
+
           ConvertToBase64(): Base64Result;
           */
 
@@ -1303,5 +1311,18 @@ export default {
       `,
       parser: require.resolve('@typescript-eslint/parser'),
     },
+    {
+      code: `
+        /**
+         * @overload
+         * @satisfies
+         */
+      `,
+      settings: {
+        jsdoc: {
+          mode: 'typescript',
+        },
+      },
+    },
   ],
 };