refactor: ts

gajus · May 14, 2023 · dd0c4bb · dd0c4bb
1 parent 6ed61d6
commit dd0c4bb
Show file tree

Hide file tree

Showing 10 changed files with 362 additions and 113 deletions.
diff --git a/docs/rules/require-jsdoc.md b/docs/rules/require-jsdoc.md
@@ -1825,7 +1825,7 @@ var a = {
   b: 1,
   c: 2
 };
-// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":[{"context":"FunctionDeclaration","minLineCount":4},{"context":"VariableDeclaration","minLineCount":5}],"require":{"FunctionDeclaration":false}}]
+// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["ClassDeclaration",{"context":"FunctionDeclaration","minLineCount":4},{"context":"VariableDeclaration","minLineCount":5}],"require":{"FunctionDeclaration":false}}]
 
 class A {
   setId(newId: number): void {

diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -17,9 +17,10 @@ import jsdocUtils from './jsdocUtils';
  * @callback CheckJsdoc
  * @param {{
  *   lastIndex?: Integer,
- *   selector: string
+ *   isFunctionContext?: boolean,
+ *   selector?: string
  * }} info
- * @param {(jsdoc: import('comment-parser').Block) => boolean|undefined} handler
+ * @param {null|((jsdoc: import('comment-parser').Block) => boolean|undefined)} handler
  * @param {import('eslint').Rule.Node} node
  * @returns {void}
  */
@@ -97,8 +98,8 @@ import jsdocUtils from './jsdocUtils';
  * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} tag
  * @param {(() => void)|null} handler
  * @param {boolean} [specRewire]
- * @param {{
- *   [key: string]: undefined|string
+ * @param {undefined|{
+ *   [key: string]: string
  * }} [data]
  */
 /* eslint-enable jsdoc/valid-types -- Old version */
@@ -218,12 +219,14 @@ import jsdocUtils from './jsdocUtils';
  * @returns {void}
  */
 
+/* eslint-disable jsdoc/no-undefined-types -- TS */
 /**
  * @callback AddLine
  * @param {Integer} sourceIndex
- * @param {import('comment-parser').Tokens} tokens
+ * @param {Partial<import('comment-parser').Tokens>} tokens
  * @returns {void}
  */
+/* eslint-enable jsdoc/no-undefined-types -- TS */
 
 /**
  * @callback AddLines
@@ -241,7 +244,7 @@ import jsdocUtils from './jsdocUtils';
 /**
  * @callback GetFunctionParameterNames
  * @param {boolean} [useDefaultObjectProperties]
- * @returns {}
+ * @returns {import('./jsdocUtils.js').ParamNameInfo[]}
  */
 
 /**
@@ -346,7 +349,7 @@ import jsdocUtils from './jsdocUtils';
 /**
  * @callback IsNamepathX
  * @param {string} tagName
- * @returns {}
+ * @returns {boolean}
  */
 
 /**
@@ -403,10 +406,17 @@ import jsdocUtils from './jsdocUtils';
 /**
  * @callback FilterTags
  * @param {(tag: import('comment-parser').Spec) => boolean} filter
- * @param {boolean} [includeInlineTags]
  * @returns {import('comment-parser').Spec[]}
  */
 
+/**
+ * @callback FilterAllTags
+ * @param {(tag: (import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
+ */
+
 /**
  * @callback GetTagsByType
  * @param {import('comment-parser').Spec[]} tags
@@ -494,6 +504,7 @@ import jsdocUtils from './jsdocUtils';
  *   getTags: GetTags,
  *   getPresentTags: GetPresentTags,
  *   filterTags: FilterTags,
+ *   filterAllTags: FilterAllTags,
  *   getTagsByType: GetTagsByType,
  *   hasOptionTag: HasOptionTag,
  *   getClassNode: GetClassNode,
@@ -659,7 +670,7 @@ const getUtils = (
   ruleConfig,
   indent,
 ) => {
-  const ancestors = context.getAncestors();
+  const ancestors = /** @type {import('eslint').Rule.Node[]} */ (context.getAncestors());
   const sourceCode = context.getSourceCode();
 
   const utils = /** @type {Utils} */ (getBasicUtils(context, settings));
@@ -1213,11 +1224,12 @@ const getUtils = (
       // istanbul ignore next
       return false;
     });
+
     for (const [
       idx,
       src,
     ] of jsdoc.source.slice(lastIndex).entries()) {
-      src.number = firstNumber + lastIndex + idx;
+      src.number = firstNumber + /** @type {Integer} */ (lastIndex) + idx;
     }
   };
 
@@ -1299,13 +1311,22 @@ const getUtils = (
 
   /** @type {IsGenerator} */
   utils.isGenerator = () => {
-    return node && (
-      node.generator ||
+    return node && Boolean(
+      /**
+       * @type {import('estree').FunctionDeclaration|
+       *   import('estree').FunctionExpression}
+       */ (node).generator ||
       node.type === 'MethodDefinition' && node.value.generator ||
       [
         'ExportNamedDeclaration', 'ExportDefaultDeclaration',
       ].includes(node.type) &&
-        node.declaration.generator
+      /** @type {import('estree').FunctionDeclaration} */
+      (
+        /**
+         * @type {import('estree').ExportNamedDeclaration|
+         *   import('estree').ExportDefaultDeclaration}
+         */ (node).declaration
+      ).generator,
     );
   };
 
@@ -1397,7 +1418,12 @@ const getUtils = (
     }
 
     if (jsdocUtils.exemptSpeciaMethods(
-      jsdoc, node, context, ruleConfig.meta.schema,
+      jsdoc,
+      node,
+      context,
+      /** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */ (
+        ruleConfig.meta.schema
+      ),
     )) {
       return true;
     }
@@ -1536,7 +1562,12 @@ const getUtils = (
     if ([
       'ExportNamedDeclaration', 'ExportDefaultDeclaration',
     ].includes(node.type)) {
-      return jsdocUtils.hasYieldValue(node.declaration);
+      return jsdocUtils.hasYieldValue(
+        /** @type {import('estree').Declaration|import('estree').Expression} */ (
+          /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */
+          (node).declaration
+        ),
+      );
     }
 
     return jsdocUtils.hasYieldValue(node);
@@ -1572,9 +1603,18 @@ const getUtils = (
   };
 
   /** @type {FilterTags} */
-  utils.filterTags = (filter, includeInlineTags = false) => {
-    const tags = jsdocUtils.getAllTags(jsdoc, includeInlineTags);
-    return jsdocUtils.filterTags(tags, filter);
+  utils.filterTags = (filter) => {
+    return jsdoc.tags.filter((tag) => {
+      return filter(tag);
+    });
+  };
+
+  /** @type {FilterAllTags} */
+  utils.filterAllTags = (filter) => {
+    const tags = jsdocUtils.getAllTags(jsdoc);
+    return tags.filter((tag) => {
+      return filter(tag);
+    });
   };
 
   /** @type {GetTagsByType} */
@@ -1734,7 +1774,7 @@ const getSettings = (context) => {
  *
  * @callback MakeReport
  * @param {import('eslint').Rule.RuleContext} context
- * @param {object} commentNode
+ * @param {import('@es-joy/jsdoccomment').Token} commentNode
  * @returns {Report}
  */
 

diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -47,7 +47,20 @@ const setTagStructure = (mode) => {
  */
 
 /**
- * @typedef {string|{
+ * @typedef {undefined|string|{
+ *   isRestProperty: boolean|undefined,
+ *   name: string,
+ *   restElement: true
+ * }|[undefined|string, FlattendRootInfo & {
+ *   annotationParamName?: string
+ * }|{
+ *   name: Integer,
+ *   restElement: boolean
+ * }[]]} ParamNameInfo
+ */
+
+/**
+ * @typedef {undefined|string|{
  *   isRestProperty: boolean,
  *   restElement: boolean,
  *   name: string
@@ -188,17 +201,6 @@ const getPropertiesFromPropertySignature = (propSignature) => {
   ).name;
 };
 
-/**
- * @typedef {undefined|{
- *   isRestProperty: boolean|undefined,
- *   name: string,
- *   restElement: true
- * }|[undefined|string, FlattendRootInfo|{
- *   name: Integer,
- *   restElement: boolean
- * }[]]} ParamNameInfo
- */
-
 /**
  * @param {ESTreeOrTypeScriptNode} functionNode
  * @param {boolean} [checkDefaultObjects]
@@ -213,7 +215,9 @@ const getFunctionParameterNames = (
    * @param {import('estree').Identifier|import('estree').AssignmentPattern|
    *   import('estree').ObjectPattern|import('estree').Property|
    *   import('estree').RestElement|import('estree').ArrayPattern|
-   *   import('@typescript-eslint/types').TSESTree.TSParameterProperty
+   *   import('@typescript-eslint/types').TSESTree.TSParameterProperty|
+   *   import('@typescript-eslint/types').TSESTree.Property|
+   *   import('@typescript-eslint/types').TSESTree.RestElement
    * } param
    * @param {boolean} [isProperty]
    * @returns {ParamNameInfo}
@@ -226,21 +230,34 @@ const getFunctionParameterNames = (
       const typeAnnotation = hasLeftTypeAnnotation ?
         /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
           param.left
-        ).typeAnnotation : param.typeAnnotation;
+        ).typeAnnotation :
+        /** @type {import('@typescript-eslint/types').TSESTree.Identifier|import('@typescript-eslint/types').TSESTree.ObjectPattern} */
+        (param).typeAnnotation;
 
       if (typeAnnotation?.typeAnnotation?.type === 'TSTypeLiteral') {
         const propertyNames = typeAnnotation.typeAnnotation.members.map((member) => {
-          return getPropertiesFromPropertySignature(member);
+          return getPropertiesFromPropertySignature(
+            /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
+            (member),
+          );
         });
+
         const flattened = {
           ...flattenRoots(propertyNames),
-          annotationParamName: param.name,
+          annotationParamName: 'name' in param ? param.name : undefined,
         };
         const hasLeftName = 'left' in param && 'name' in param.left;
 
         if ('name' in param || hasLeftName) {
           return [
-            hasLeftName ? param.left.name : param.name, flattened,
+            hasLeftName ?
+              /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+                param.left
+              ).name :
+              /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
+                param
+              ).name,
+            flattened,
           ];
         }
 
@@ -258,8 +275,22 @@ const getFunctionParameterNames = (
       return param.left.name;
     }
 
-    if (param.type === 'ObjectPattern' || param.left?.type === 'ObjectPattern') {
-      const properties = param.properties || param.left?.properties;
+    if (
+      param.type === 'ObjectPattern' ||
+      ('left' in param &&
+      (
+        param
+      ).left.type === 'ObjectPattern')
+    ) {
+      const properties = /** @type {import('@typescript-eslint/types').TSESTree.ObjectPattern} */ (
+        param
+      ).properties ||
+        /** @type {import('estree').ObjectPattern} */
+        (
+          /** @type {import('@typescript-eslint/types').TSESTree.AssignmentPattern} */ (
+            param
+          ).left
+        )?.properties;
       const roots = properties.map((prop) => {
         return getParamName(prop, true);
       });
@@ -557,7 +588,7 @@ const isValidTag = (
 };
 
 /**
- * @param {object} jsdoc
+ * @param {import('comment-parser').Block} jsdoc
  * @param {string} targetTagName
  * @returns {boolean}
  */
@@ -575,12 +606,11 @@ const hasTag = (jsdoc, targetTagName) => {
  * @param {import('comment-parser').Block & {
  *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
  * }} jsdoc
- * @param {boolean} includeInlineTags
  * @returns {(import('comment-parser').Spec|
  *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
-const getAllTags = (jsdoc, includeInlineTags) => {
-  return includeInlineTags ? [
+const getAllTags = (jsdoc) => {
+  return [
     ...jsdoc.tags,
     ...jsdoc.inlineTags.map((inlineTag) => {
       // Tags don't have source or line numbers, so add before returning
@@ -640,11 +670,11 @@ const getAllTags = (jsdoc, includeInlineTags) => {
         ).inlineTags
       );
     }),
-  ] : jsdoc.tags;
+  ];
 };
 
 /**
- * @param {object} jsdoc
+ * @param {import('comment-parser').Block} jsdoc
  * @param {string[]} targetTagNames
  * @returns {boolean}
  */
@@ -1293,17 +1323,6 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
   return properties;
 };
 
-/**
- * @param {import('comment-parser').Spec[]} tags
- * @param {(tag: import('comment-parser').Spec) => boolean} filter
- * @returns {import('comment-parser').Spec[]}
- */
-const filterTags = (tags, filter) => {
-  return tags.filter((tag) => {
-    return filter(tag);
-  });
-};
-
 const tagsWithNamesAndDescriptions = new Set([
   'param', 'arg', 'argument', 'property', 'prop',
   'template',
@@ -1337,7 +1356,7 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
    * @type {import('comment-parser').Spec[]}
    */
   const tagsWithoutNames = [];
-  const tagsWithNames = filterTags(tags, (tag) => {
+  const tagsWithNames = tags.filter((tag) => {
     const {
       tag: tagName,
     } = tag;
@@ -1522,7 +1541,6 @@ export default {
   dropPathSegmentQuotes,
   enforcedContexts,
   exemptSpeciaMethods,
-  filterTags,
   flattenRoots,
   getAllTags,
   getContextObject,