parser does not recognize JSDoc blocks without initial whitespace

[stoicbuddha]

Description:

When using JSDoc to define a typedef with an import statement, the linter fails with the rule jsdoc/no-undefined-types when the import statement is referencing a type defined in another file purely based on spacing.

Steps to Reproduce:

Define a JSDoc typedef with an import statement referencing a type from another file, for example:
javascript

/**@typedef {import('restify').Request} Request */ // Passes linter just fine
/**@typedef {import('./types').helperError} helperError */ // Fails linter

Expected Behavior:

The linter should recognize the import statement and not raise any errors for the typedef definition; for the sake of consistency, it should either error on both or error on neither.

Actual Behavior:

The linter fails on the import for helperError with the rule jsdoc/no-undefined-types, indicating that the imported type is undefined, despite being properly recognized by VS Code.

Note that the following works properly and passes the linter:

/** @typedef {import('./types').helperError} helperError */

The behavior is inconsistent.

ESLint Config

module.exports = {
	env: {
		browser: true,
		commonjs: true,
		es2021: true,
	},
	extends: "plugin:jsdoc/recommended-typescript-flavor",
	overrides: [
		{
			env: {
				node: true,
			},
			files: [".eslintrc.{js,cjs}"],
			parserOptions: {
				sourceType: "script",
			},
		},
	],
	plugins: ["jsdoc"],
	parserOptions: {
		ecmaVersion: "latest",
	},
	ignorePatterns: ["**/node_modules/*"],
	rules: {
		"jsdoc/check-access": 1, // Recommended
		"jsdoc/check-alignment": 1, // Recommended
		"jsdoc/check-param-names": 1, // Recommended
		"jsdoc/check-property-names": 1, // Recommended
		"jsdoc/check-syntax": 1,
		"jsdoc/check-tag-names": 1, // Recommended
		"jsdoc/check-types": 1, // Recommended
		"jsdoc/check-values": 1, // Recommended
		"jsdoc/empty-tags": 1, // Recommended
		"jsdoc/implements-on-classes": 1, // Recommended
		"jsdoc/multiline-blocks": 1, // Recommended
		"jsdoc/no-bad-blocks": 1,
		"jsdoc/no-blank-block-descriptions": 1,
		"jsdoc/no-defaults": 1,
		"jsdoc/no-multi-asterisks": 1, // Recommended
		"jsdoc/no-undefined-types": 1, // Recommended
		"jsdoc/require-asterisk-prefix": 1,
		"jsdoc/require-description": 0,
		"jsdoc/require-jsdoc": 1, // Recommended
		"jsdoc/require-param": 1, // Recommended
		"jsdoc/require-param-description": 0, // Recommended
		"jsdoc/require-param-name": 1, // Recommended
		"jsdoc/require-param-type": 1, // Recommended
		"jsdoc/require-property": 1, // Recommended
		"jsdoc/require-property-description": 1, // Recommended
		"jsdoc/require-property-name": 1, // Recommended
		"jsdoc/require-property-type": 1, // Recommended
		"jsdoc/require-returns": 1, // Recommended
		"jsdoc/require-returns-check": 1, // Recommended
		"jsdoc/require-returns-description": 0, // Recommended
		"jsdoc/require-returns-type": 1, // Recommended
		"jsdoc/require-throws": 1,
		"jsdoc/require-yields": 1, // Recommended
		"jsdoc/require-yields-check": 1, // Recommended
		"jsdoc/tag-lines": 0,
		"jsdoc/sort-tags": 0,
		"jsdoc/valid-types": 1, // Recommended
	},
	settings: {
		jsdoc: {
			mode: "typescript",
		},
	},
};

Environment

Node version: v18.19.1
ESLint Version: v8.57.0
eslint-plugin-jsdoc: 48.2.1

[brettz9]

I'm almost certain that in source code if not in its docs, the original JSDoc tool called for whitespace after the initial /**. However, as you are using the TypeScript mode (now the default also), we'd ideally be using comment parsing as used by TypeScript.

It does seem though that TSDoc, a spec/tool for parsing JSDoc comments for TypeScript, allows for no whitespace. Ideally then, we'd use a tool like @microsoft/tsdoc in place of comment-parser. This might also be useful in a few other edge cases like #1116 .

However, this would most likely require a high degree of refactoring, and it is not one I am inclined to undertake myself (it'd also require changes in @es-joy/jsdoccomment). A PR would be welcome, however.