.eslintrc.json

@@ -37,6 +37,7 @@
     "unicorn/no-unsafe-regex": 0,
     "unicorn/prefer-array-some": 0,
     "unicorn/prevent-abbreviations": 0,
+    "unicorn/import-index": 0,
     "linebreak-style": 0,
     "no-inline-comments": 0,
     "no-extra-parens": 0

docs/rules/no-undefined-types.md

@@ -283,6 +283,24 @@ function foo () {
 const a = new Todo();
 // Settings: {"jsdoc":{"mode":"jsdoc"}}
 // Message: The type 'Omit' is undefined.
+
+/**
+ * Message with {@link NotKnown}
+ */
+// Message: The type 'NotKnown' is undefined.
+
+/**
+ * Message with
+ * a link that is {@link NotKnown}
+ */
+// Message: The type 'NotKnown' is undefined.
+
+/**
+ * @abc
+ * @someTag Message with
+ *   a link that is {@link NotKnown}
+ */
+// Message: The type 'NotKnown' is undefined.
 ````
 
 

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.38.0",
+    "@es-joy/jsdoccomment": "~0.39.1",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.3.1",
     "debug": "^4.3.4",
@@ -29,8 +29,15 @@
     "@semantic-release/commit-analyzer": "^9.0.2",
     "@semantic-release/github": "^8.0.7",
     "@semantic-release/npm": "^10.0.3",
+    "@types/chai": "^4.3.5",
+    "@types/debug": "^4.1.7",
     "@types/eslint": "^8.37.0",
-    "@types/node": "^20.1.1",
+    "@types/estree": "^1.0.1",
+    "@types/lodash.defaultsdeep": "^4.6.7",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^20.1.2",
+    "@types/semver": "^7.5.0",
+    "@types/spdx-expression-parse": "^3.0.2",
     "@typescript-eslint/parser": "^5.59.5",
     "babel-plugin-add-module-exports": "^1.0.4",
     "babel-plugin-istanbul": "^6.1.1",
@@ -41,7 +48,7 @@
     "eslint": "8.39.0",
     "eslint-config-canonical": "~33.0.1",
     "gitdown": "^3.1.5",
-    "glob": "^10.2.2",
+    "glob": "^10.2.3",
     "husky": "^8.0.3",
     "jsdoc-type-pratt-parser": "^4.0.0",
     "lint-staged": "^13.2.2",

src/index.js

@@ -51,13 +51,11 @@ import tagLines from './rules/tagLines';
 import textEscaping from './rules/textEscaping';
 import validTypes from './rules/validTypes';
 
+/**
+ * @type {import('eslint').ESLint.Plugin}
+ */
 const index = {
-  /* eslint-disable jsdoc/no-undefined-types -- Bug */
-  /**
-   * @type {Record<string, import('eslint').ESLint.ConfigData<import('eslint').Linter.RulesRecord>>}
-   */
   configs: {},
-  /* eslint-enable jsdoc/no-undefined-types -- Bug */
   rules: {
     'check-access': checkAccess,
     'check-alignment': checkAlignment,
@@ -206,6 +204,11 @@ const createRecommendedTypeScriptRuleset = (warnOrError) => {
   };
 };
 
+/* istanbul ignore if -- TS */
+if (!index.configs) {
+  throw new Error('TypeScript guard');
+}
+
 index.configs.recommended = createRecommendedRuleset('warn');
 index.configs['recommended-error'] = createRecommendedRuleset('error');
 index.configs['recommended-typescript'] = createRecommendedTypeScriptRuleset('warn');

src/rules/checkLineAlignment.js

@@ -157,7 +157,7 @@ const checkAlignment = ({
   if (comment !== formatted) {
     report(
       'Expected JSDoc block lines to be aligned.',
-      (fixer) => {
+      /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
         return fixer.replaceText(jsdocNode, formatted);
       },
     );

src/rules/checkTypes.js

@@ -375,7 +375,7 @@ export default iterateJsdoc(({
       const fixedType = stringify(typeAst);
 
       /**
-       * @param {any} fixer The ESLint fixer
+       * @param {import('eslint').Rule.ReportFixer} fixer The ESLint fixer
        * @returns {string}
        */
       const fix = (fixer) => {

src/rules/emptyTags.js

@@ -41,6 +41,7 @@ export default iterateJsdoc(({
       settings.mode === 'closure' && emptyIfClosure.has(tagName) ||
       settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
   });
+
   for (const tag of emptyTags) {
     const content = tag.name || tag.description || tag.type;
     if (content.trim()) {

src/rules/matchDescription.js

@@ -32,7 +32,7 @@ export default iterateJsdoc(({
     }
 
     if (mainDescriptionMatch === false && (
-      !tag || !Object.prototype.hasOwnProperty.call(tags, tag.tag))
+      !tag || !Object.hasOwn(tags, tag.tag))
     ) {
       return;
     }

src/rules/noBadBlocks.js

@@ -66,7 +66,7 @@ export default iterateJsdoc(({
     const report = makeReport(context, node);
 
     // eslint-disable-next-line no-loop-func
-    const fix = (fixer) => {
+    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
       const text = sourceCode.getText(node);
 
       return fixer.replaceText(

src/rules/requireDescriptionCompleteSentence.js

@@ -79,7 +79,7 @@ const validateDescription = (
   return paragraphs.some((paragraph, parIdx) => {
     const sentences = extractSentences(paragraph, abbreviationsRegex);
 
-    const fix = (fixer) => {
+    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
       let text = sourceCode.getText(jsdocNode);
 
       if (!/[.:?!]$/u.test(paragraph)) {

src/rules/requireJsdoc.js

@@ -205,6 +205,7 @@ const getOptions = (context, settings) => {
   };
 };
 
+/** @type {import('eslint').Rule.RuleModule} */
 export default {
   create (context) {
     const sourceCode = context.getSourceCode();
@@ -287,7 +288,7 @@ export default {
         }
       }
 
-      const fix = (fixer) => {
+      const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
         // Default to one line break if the `minLines`/`maxLines` settings allow
         const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
         let baseNode = getReducedASTNode(node, sourceCode);
@@ -450,7 +451,7 @@ export default {
     docs: {
       category: 'Stylistic Issues',
       description: 'Require JSDoc comments',
-      recommended: 'true',
+      recommended: true,
       url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-jsdoc',
     },
 

src/tagNames.js

@@ -1,10 +1,24 @@
+/* eslint-disable jsdoc/valid-types -- Old version */
+/**
+ * @typedef {{
+ *   [key: string]: string[]
+ * }} AliasedTags
+ */
+/* eslint-enable jsdoc/valid-types -- Old version */
+
+/**
+ * @type {AliasedTags}
+ */
 const jsdocTagsUndocumented = {
   // Undocumented but present; see
   // https://github.com/jsdoc/jsdoc/issues/1283#issuecomment-516816802
   // https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js#L594
   modifies: [],
 };
 
+/**
+ * @type {AliasedTags}
+ */
 const jsdocTags = {
   ...jsdocTagsUndocumented,
   abstract: [
@@ -118,6 +132,9 @@ const jsdocTags = {
   ],
 };
 
+/**
+ * @type {AliasedTags}
+ */
 const typeScriptTags = {
   ...jsdocTags,
 
@@ -135,6 +152,9 @@ const typeScriptTags = {
   template: [],
 };
 
+/**
+ * @type {AliasedTags}
+ */
 const undocumentedClosureTags = {
   // These are in Closure source but not in jsdoc source nor in the Closure
   //  docs: https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/Annotation.java
@@ -165,6 +185,9 @@ const {
   ...typeScriptTagsInClosure
 } = typeScriptTags;
 
+/**
+ * @type {AliasedTags}
+ */
 const closureTags = {
   ...typeScriptTagsInClosure,
   ...undocumentedClosureTags,

src/utils/hasReturnValue.js

@@ -1,16 +1,26 @@
 /* eslint-disable jsdoc/no-undefined-types */
+
+/**
+ * @typedef {import('estree').Node|
+ *   import('@typescript-eslint/types').TSESTree.TSTypeReference} ESTreeOrTypeScriptNode
+ */
+
 /**
  * Checks if a node is a promise but has no resolve value or an empty value.
  * An `undefined` resolve does not count.
  *
- * @param {object} node
+ * @param {ESTreeOrTypeScriptNode} node
  * @returns {boolean}
  */
 const isNewPromiseExpression = (node) => {
   return node && node.type === 'NewExpression' && node.callee.type === 'Identifier' &&
     node.callee.name === 'Promise';
 };
 
+/**
+ * @param {import('@typescript-eslint/types').TSESTree.TSTypeReference} node
+ * @returns {boolean}
+ */
 const isVoidPromise = (node) => {
   return node?.typeParameters?.params?.[0]?.type === 'TSVoidKeyword';
 };
@@ -22,10 +32,10 @@ const undefinedKeywords = new Set([
 /**
  * Checks if a node has a return statement. Void return does not count.
  *
- * @param {object} node
+ * @param {import('estree').Node|import('@typescript-eslint/types').TSESTree.Node} node
  * @param {boolean} throwOnNullReturn
  * @param {PromiseFilter} promFilter
- * @returns {boolean|Node}
+ * @returns {boolean|undefined}
  */
 // eslint-disable-next-line complexity
 const hasReturnValue = (node, throwOnNullReturn, promFilter) => {
@@ -46,7 +56,7 @@ const hasReturnValue = (node, throwOnNullReturn, promFilter) => {
   case 'FunctionExpression':
   case 'FunctionDeclaration':
   case 'ArrowFunctionExpression': {
-    return node.expression && (!isNewPromiseExpression(node.body) || !isVoidPromise(node.body)) ||
+    return 'expression' in node && node.expression && (!isNewPromiseExpression(node.body) || !isVoidPromise(node.body)) ||
       hasReturnValue(node.body, throwOnNullReturn, promFilter);
   }
 
@@ -117,7 +127,7 @@ const hasReturnValue = (node, throwOnNullReturn, promFilter) => {
  *
  * @param {object} node
  * @param {PromiseFilter} promFilter
- * @returns {boolean|Node}
+ * @returns {boolean|import('estree').Node}
  */
 // eslint-disable-next-line complexity
 const allBrancheshaveReturnValues = (node, promFilter) => {

test/iterateJsdoc.js

@@ -12,6 +12,7 @@ describe('iterateJsdoc', () => {
     context('options', () => {
       it('throws with missing options', () => {
         expect(() => {
+          // @ts-expect-error Bad arguments
           iterateJsdoc(() => {});
         }).to.throw(TypeError);
       });
@@ -21,6 +22,7 @@ describe('iterateJsdoc', () => {
         context('Invalid iterator', () => {
           it('throws with missing function', () => {
             expect(() => {
+              // @ts-expect-error Bad argument
               iterateJsdoc(undefined, {
                 meta: {
                   type: 'suggestion',
@@ -30,6 +32,7 @@ describe('iterateJsdoc', () => {
           });
           it('throws with object missing `returns` method', () => {
             expect(() => {
+              // @ts-expect-error Bad argument
               iterateJsdoc({}, {
                 meta: {
                   type: 'suggestion',
@@ -41,6 +44,7 @@ describe('iterateJsdoc', () => {
         context('Invalid options', () => {
           it('throws with missing meta', () => {
             expect(() => {
+              // @ts-expect-error Bad argument
               iterateJsdoc(() => {}, {});
             }).to.throw(TypeError);
           });

test/jsdocUtils.js

@@ -71,7 +71,7 @@ describe('jsdocUtils', () => {
   describe('mayBeUndefinedTypeTag()', () => {
     context('Missing tag', () => {
       it('should return `false` with a missing tag', () => {
-        expect(jsdocUtils.mayBeUndefinedTypeTag(null)).to.equal(true);
+        expect(jsdocUtils.mayBeUndefinedTypeTag(null, 'permissive')).to.equal(true);
       });
     });
   });

test/rules/assertions/checkTagNames.js

@@ -2,17 +2,31 @@ import {
   jsdocTags,
   typeScriptTags,
   closureTags,
-} from '../../../src/tagNames';
+} from '../../../src/tagNames.js';
 
+/**
+ * @param {import('../../../src/tagNames.js').AliasedTags} tags
+ * @returns {string}
+ */
 const buildTagBlock = (tags) => {
   return '/** \n * @' + Object.keys(tags).map((tagName, idx) => {
     return (idx === 0 ? '' : '\n * @') + tagName;
   })
     .join('') + '\n */';
 };
 
+/**
+ * @typedef {number} Integer
+ */
+
+/**
+ * @param {string} code
+ * @returns {Integer}
+ */
 const lineCount = (code) => {
-  return code.match(/\n/ug).length;
+  /* eslint-disable jsdoc/no-undefined-types -- TS */
+  return /** @type {RegExpMatchArray} */ (code.match(/\n/ug)).length;
+  /* eslint-enable jsdoc/no-undefined-types -- TS */
 };
 
 // We avoid testing all closure tags as too many

test/rules/assertions/noUndefinedTypes.js

@@ -490,6 +490,48 @@ export default {
         },
       },
     },
+    {
+      code: `
+      /**
+       * Message with {@link NotKnown}
+       */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'The type \'NotKnown\' is undefined.',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * Message with
+       * a link that is {@link NotKnown}
+       */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'The type \'NotKnown\' is undefined.',
+        },
+      ],
+    },
+    {
+      code: `
+      /**
+       * @abc
+       * @someTag Message with
+       *   a link that is {@link NotKnown}
+       */
+      `,
+      errors: [
+        {
+          line: 5,
+          message: 'The type \'NotKnown\' is undefined.',
+        },
+      ],
+    },
   ],
   valid: [
     {

test/rules/index.js

@@ -1,3 +1,11 @@
+import {
+  readFileSync,
+} from 'fs';
+import {
+  // dirname,
+  join,
+} from 'path';
+// import {fileURLToPath} from 'url';
 import camelCase from 'camelcase';
 import {
   ESLint,
@@ -6,29 +14,45 @@ import {
 import pkg from 'eslint/use-at-your-own-risk';
 import defaultsDeep from 'lodash.defaultsdeep';
 import semver from 'semver';
-import config from '../../src';
-import ruleNames from './ruleNames.json';
+import config from '../../src/index.js';
+
+// const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const ruleTester = new RuleTester();
 const {
   FlatRuleTester,
 } = pkg;
 
 const main = async () => {
+  const ruleNames = JSON.parse(readFileSync(join(__dirname, './ruleNames.json'), 'utf8'));
+
+  if (!config.rules) {
+    throw new Error('TypeScript guard');
+  }
+
   for (const ruleName of process.env.npm_config_rule ? process.env.npm_config_rule.split(',') : ruleNames) {
     if (semver.gte(ESLint.version, '8.0.0') && ruleName === 'check-examples') {
       // TODO: This rule cannot yet be supported for ESLint 8;
       // The possibility for ESLint 8 support is being tracked at https://github.com/eslint/eslint/issues/14745
       continue;
     }
 
-    const rule = config.rules[ruleName];
+    const rule = /** @type {import('eslint').Rule.RuleModule} */ (
+      config.rules[ruleName]
+    );
 
     const parserOptions = {
       ecmaVersion: 6,
     };
 
     // Catch syntax errors
+
+    /**
+     * @type {{
+     *   invalid: import('eslint').RuleTester.InvalidTestCase[],
+     *   valid: import('eslint').RuleTester.ValidTestCase[]
+     * }}
+     */
     let assertions;
     try {
       assertions = (await import(`./assertions/${camelCase(ruleName)}`)).default;
@@ -38,7 +62,7 @@ const main = async () => {
       return;
     }
 
-    if (!('meta' in rule && 'schema' in rule.meta) && (
+    if (!(rule.meta && 'schema' in rule.meta) && (
       assertions.invalid.some((item) => {
         return item.options;
       }) ||
@@ -56,7 +80,9 @@ const main = async () => {
     assertions.invalid = assertions.invalid.map((assertion) => {
       Reflect.deleteProperty(assertion, 'ignoreReadme');
       assertion.parserOptions = defaultsDeep(assertion.parserOptions, parserOptions);
-      for (const error of assertion.errors) {
+      for (const error of /** @type {import('eslint').RuleTester.TestCaseError[]} */ (
+        assertion.errors
+      )) {
         if (!('line' in error)) {
           count++;
         }
@@ -83,10 +109,12 @@ const main = async () => {
 
     assertions.valid = assertions.valid.map((assertion) => {
       Reflect.deleteProperty(assertion, 'ignoreReadme');
+      // @ts-expect-error Bad valid format
       if (assertion.errors) {
         throw new Error(`Valid assertions for rule ${ruleName} should not have an \`errors\` array.`);
       }
 
+      // @ts-expect-error Bad valid format
       if (assertion.output) {
         throw new Error(`Valid assertions for rule ${ruleName} should not have an \`output\` property.`);
       }

tsconfig.json

@@ -13,7 +13,11 @@
     "target": "es6",
     "outDir": "dist"
   },
-  // Restore to `src/**/*.js` as ready
-  "include": ["src/bin/*.js", "src/bin/gitdown.d.ts"],
+  // Uncomment below as ready
+  "include": [
+    // "src/**/*.js",
+    // "test/**/*.js",
+    "src/bin/gitdown.d.ts"
+  ],
   "exclude": ["node_modules"]
 }