Variable reference not recognized correctly inside @typedef

[danfuzz]

Expected behavior

A variable reference (specifically an imported value) is correctly recognized inside a @typedef and will ensure that the variable in question is treated as "used."

Actual behavior

In such a case, assuming no other references, the variable definition in question is treated as unused, as in the error:

  1:8  error  'fs' is defined but never used  no-unused-vars

But, if the variable definition (e.g. the import) is removed / commented out, then that also turns into an error because it isn't defined, as in the error:

  4:1  warning  The type 'fs' is undefined  jsdoc/no-undefined-types

Somehow, the @typedef both does and doesn't reference the variable. Wacky!

ESLint Config

import js from '@eslint/js';
import jsdocPlugin from 'eslint-plugin-jsdoc';
import globals from 'globals';

export default [
  js.configs.recommended,
  jsdocPlugin.configs['flat/recommended'],
  {
    languageOptions: {
      ecmaVersion: 2024,
      globals: globals.node
    },
    plugins: {
      'jsdoc': jsdocPlugin,
    },
    settings: {
      jsdoc: {
        mode: 'jsdoc'
      }
    }
  },
];

ESLint sample

import fs from 'node:fs/promises';

/**
 * @typedef {{ path: string, stats: fs.Stats } | { redirect: string } | null } Blorp
 */

/**
 * @returns {Blorp} The resolution.
 */
export function x() {
  return null;
}

You can see the two errors above by either leaving the import line as-is or commenting it out.

In case it's handy, here's a tarball of the example. You can unpack it and then run ./demo:

bug-report.tar.gz

Environment

• Node version: 23.6.0
• ESLint version 9.18.0
• eslint-plugin-jsdoc version: 50.6.1