refactor: TS

gajus · May 16, 2023 · 36c9166 · 36c9166
1 parent 1350ed6
commit 36c9166
Show file tree

Hide file tree

Showing 4 changed files with 169 additions and 71 deletions.
diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -323,7 +323,7 @@ import {
 /**
  * @callback ComparePaths
  * @param {string} name
- * @returns {(otherPathName: string) => void}
+ * @returns {(otherPathName: string) => boolean}
  */
 
 /**

diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -37,39 +37,42 @@ const setTagStructure = (mode) => {
   tagStructure = getDefaultTagStructureForMode(mode);
 };
 
-/**
- * @typedef {{
- *   hasPropertyRest: boolean,
- *   hasRestElement: boolean,
- *   names: string[],
- *   rests: boolean[],
- * }} FlattendRootInfo
- */
-
 /**
  * @typedef {undefined|string|{
+ *   name: Integer,
+ *   restElement: boolean
+ * }|{
  *   isRestProperty: boolean|undefined,
  *   name: string,
- *   restElement: true
- * }|[undefined|string, FlattendRootInfo & {
- *   annotationParamName?: string
+ *   restElement: boolean
  * }|{
- *   name: Integer,
+ *   name: string,
  *   restElement: boolean
- * }[]]} ParamNameInfo
+ * }} ParamCommon
+ */
+/**
+ * @typedef {ParamCommon|[string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string,
+ * })]|NestedParamInfo} ParamNameInfo
  */
 
 /**
- * @typedef {undefined|string|{
- *   isRestProperty: boolean,
- *   restElement: boolean,
- *   name: string
- * }|[string, {
+ * @typedef {{
  *   hasPropertyRest: boolean,
  *   hasRestElement: boolean,
  *   names: string[],
  *   rests: boolean[],
- * }]|[string, string[]]} ParamInfo
+ * }} FlattendRootInfo
+ */
+/**
+ * @typedef {[string, (string[]|ParamInfo[])]} NestedParamInfo
+ */
+/**
+ * @typedef {ParamCommon|
+ * [string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string
+ * })]|
+ * NestedParamInfo} ParamInfo
  */
 
 /**
@@ -123,28 +126,28 @@ const flattenRoots = (params, root = '') => {
           hasPropertyRest = true;
         }
 
-        const inner = [
+        const inner = /** @type {string[]} */ ([
           root ? `${root}.${cur[0]}` : cur[0],
           ...flattened.names,
-        ].filter(Boolean);
+        ].filter(Boolean));
         rests.push(false, ...flattened.rests);
 
         return acc.concat(inner);
       }
 
       if (typeof cur === 'object') {
-        if (cur.isRestProperty) {
+        if ('isRestProperty' in cur && cur.isRestProperty) {
           hasPropertyRest = true;
           rests.push(true);
         } else {
           rests.push(false);
         }
 
-        if (cur.restElement) {
+        if ('restElement' in cur && cur.restElement) {
           hasRestElement = true;
         }
 
-        acc.push(root ? `${root}.${cur.name}` : cur.name);
+        acc.push(root ? `${root}.${String(cur.name)}` : String(cur.name));
       } else if (typeof cur !== 'undefined') {
         rests.push(false);
         acc.push(root ? `${root}.${cur}` : cur);
@@ -219,10 +222,11 @@ const getFunctionParameterNames = (
    *   import('@typescript-eslint/types').TSESTree.RestElement|
    *   import('@typescript-eslint/types').TSESTree.Identifier|
    *   import('@typescript-eslint/types').TSESTree.ObjectPattern|
-   *   import('@typescript-eslint/types').TSESTree.BindingName
+   *   import('@typescript-eslint/types').TSESTree.BindingName|
+   *   import('@typescript-eslint/types').TSESTree.Parameter
    * } param
    * @param {boolean} [isProperty]
-   * @returns {ParamNameInfo}
+   * @returns {ParamNameInfo|[string, ParamNameInfo[]]}
    */
   const getParamName = (param, isProperty) => {
     /* eslint-enable complexity -- Temporary */
@@ -305,9 +309,10 @@ const getFunctionParameterNames = (
     if (param.type === 'Property') {
       // eslint-disable-next-line default-case
       switch (param.value.type) {
-      case 'ArrayPattern':
+      case 'ArrayPattern': {
         return [
-          param.key.name,
+          /** @type {import('estree').Identifier} */
+          (param.key).name,
           /** @type {import('estree').ArrayPattern} */ (
             param.value
           ).elements.map((prop, idx) => {
@@ -317,42 +322,57 @@ const getFunctionParameterNames = (
             };
           }),
         ];
-      case 'ObjectPattern':
+      }
+
+      case 'ObjectPattern': {
         return [
-          param.key.name,
+          /** @type {import('estree').Identifier} */ (param.key).name,
           /** @type {import('estree').ObjectPattern} */ (
             param.value
           ).properties.map((prop) => {
-            return getParamName(prop, isProperty);
+            return /** @type {string|[string, string[]]} */ (getParamName(prop, isProperty));
           }),
         ];
+      }
+
       case 'AssignmentPattern': {
         // eslint-disable-next-line default-case
         switch (param.value.left.type) {
         case 'Identifier':
           // Default parameter
           if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
             return [
-              param.key.name, /** @type {import('estree').AssignmentPattern} */ (
+              /** @type {import('estree').Identifier} */ (
+                param.key
+              ).name,
+              /** @type {import('estree').AssignmentPattern} */ (
                 param.value
               ).right.properties.map((prop) => {
-                return getParamName(prop, isProperty);
+                return /** @type {string} */ (getParamName(
+                  /** @type {import('estree').Property} */
+                  (prop),
+                  isProperty,
+                ));
               }),
             ];
           }
 
           break;
         case 'ObjectPattern':
           return [
-            param.key.name, /** @type {import('estree').ObjectPattern} */ (
+            /** @type {import('estree').Identifier} */
+            (param.key).name,
+            /** @type {import('estree').ObjectPattern} */ (
               param.value.left
             ).properties.map((prop) => {
               return getParamName(prop, isProperty);
             }),
           ];
         case 'ArrayPattern':
           return [
-            param.key.name, /** @type {import('estree').ArrayPattern} */ (
+            /** @type {import('estree').Identifier} */
+            (param.key).name,
+            /** @type {import('estree').ArrayPattern} */ (
               param.value.left
             ).elements.map((prop, idx) => {
               return {
@@ -371,9 +391,9 @@ const getFunctionParameterNames = (
 
       // The key of an object could also be a string or number
       case 'Literal':
-        return param.key.raw ||
+        return /** @type {string} */ (param.key.raw ||
           // istanbul ignore next -- `raw` may not be present in all parsers
-          param.key.value;
+          param.key.value);
 
       // case 'MemberExpression':
       default:
@@ -385,11 +405,18 @@ const getFunctionParameterNames = (
       }
     }
 
-    if (param.type === 'ArrayPattern' || param.left?.type === 'ArrayPattern') {
+    if (
+      param.type === 'ArrayPattern' ||
+      /** @type {import('estree').AssignmentPattern} */ (
+        param
+      ).left?.type === 'ArrayPattern'
+    ) {
       const elements = /** @type {import('estree').ArrayPattern} */ (
         param
       ).elements || /** @type {import('estree').ArrayPattern} */ (
-        param.left
+        /** @type {import('estree').AssignmentPattern} */ (
+          param
+        ).left
       )?.elements;
       const roots = elements.map((prop, idx) => {
         return {
@@ -408,7 +435,10 @@ const getFunctionParameterNames = (
     ].includes(param.type)) {
       return {
         isRestProperty: isProperty,
-        name: param.argument.name,
+        name: /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+          /** @type {import('@typescript-eslint/types').TSESTree.RestElement} */ (
+            param
+          ).argument).name,
         restElement: true,
       };
     }
@@ -431,7 +461,11 @@ const getFunctionParameterNames = (
     return [];
   }
 
-  return (functionNode.params || functionNode.value?.params || []).map((param) => {
+  return (/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (
+    functionNode
+  ).params || /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */ (
+    functionNode
+  ).value?.params || []).map((param) => {
     return getParamName(param);
   });
 };
@@ -1570,7 +1604,7 @@ const dropPathSegmentQuotes = (str) => {
 
 /**
  * @param {string} name
- * @returns {(otherPathName: string) => void}
+ * @returns {(otherPathName: string) => boolean}
  */
 const comparePaths = (name) => {
   return (otherPathName) => {

diff --git a/src/rules/checkParamNames.js b/src/rules/checkParamNames.js
@@ -103,7 +103,11 @@ const validateParameterNames = (
           rests,
           annotationParamName,
         },
-      ] = functionParameterName;
+      ] =
+        /**
+         * @type {[string | undefined, import('../jsdocUtils.js').FlattendRootInfo & {
+         *   annotationParamName?: string | undefined;
+          }]} */ (functionParameterName);
       if (annotationParamName !== undefined) {
         const name = tag.name.trim();
         if (name !== annotationParamName) {
@@ -127,6 +131,8 @@ const validateParameterNames = (
       });
 
       const missingProperties = [];
+
+      /** @type {string[]} */
       const notCheckingNames = [];
 
       for (const [
@@ -173,6 +179,7 @@ const validateParameterNames = (
       }
 
       if (!hasPropertyRest || checkRestProperty) {
+        /** @type {[string, import('comment-parser').Spec][]} */
         const extraProperties = [];
         for (const [
           idx,
@@ -228,7 +235,10 @@ const validateParameterNames = (
         return name.trim();
       });
       const expectedNames = functionParameterNames.map((item, idx) => {
-        if (item?.[1]?.names) {
+        if (/**
+             * @type {[string|undefined, (import('../jsdocUtils.js').FlattendRootInfo & {
+             *   annotationParamName?: string,
+              })]} */ (item)?.[1]?.names) {
           return actualNames[idx];
         }
 
@@ -324,14 +334,14 @@ export default iterateJsdoc(({
   const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
 
   const jsdocParameterNamesDeep = utils.getJsdocTagsDeep('param');
-  if (!jsdocParameterNamesDeep.length) {
+  if (!jsdocParameterNamesDeep || !jsdocParameterNamesDeep.length) {
     return;
   }
 
   const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties);
-  const targetTagName = utils.getPreferredTagName({
+  const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
     tagName: 'param',
-  });
+  }));
   const isError = validateParameterNames(
     targetTagName,
     allowExtraTrailingParamDocs,