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

[zshuzh]

I have also run into this issue when attempting to migrate a repo to ESLint's new flat config. AFAICT the issue is exclusive to the flat config. I was able to verify this using the example provided above — if you download the tarball, delete the eslint.config.mjs file, and replace it with a .eslintrc.json file with the following contents:

{
  "plugins": ["jsdoc"],
  "extends": ["plugin:jsdoc/recommended"],
  "parserOptions": {
    "ecmaVersion": 2020,
    "sourceType": "module"
  }
}

and then run the demo with ESLINT_USE_FLAT_CONFIG=false ./demo, then the error:

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

no longer appears, which is the expected behaviour.