fix(no-undefined-types): support strict validation for TS namespaces

[risantos]

Description

This PR updates the no-undefined-types rule to support strict validation of TypeScript namespaces. Previously, the rule might have been too permissive or failed to recognize types defined within namespaces in the same file.

This became an issue recently with an update that led to definedTypes matching a declared namespace on a .d.ts file starting to report their inner properties/types/interfaces as undefined.

An example would be configuring the no-undefined-types with:

'jsdoc/no-undefined-types': ['error', { definedTypes: ['Foobar'] }],

while having a .d.ts file with something such as the following:

export type * as Foobiz from './foobiz';
export interface FoobarInterface {
  foo: string;
  bar: number;
}

export as namespace Foobar;

And then wanting to use Foobar.FoobarInterface, Foobar.FoobarInterface['foo'], or Foobar.Foobiz.biz as types on JSDoc. The TS LSP would recognize them, but this rule started reporting errors.

/**
 * @param {Foobar.FoobarInterface} foobarInterface - Foobar interface.
 * @returns {{ biz: Foobar.FoobarInterface['bar'], foo: Foobar.FoobarInterface['foo'] }} Biz and Foo.
 */
const functionOverFoobarInterface = foobarInterface => {
  const { bar, foo } = foobarInterface;

  return { biz: bar * 2, foo };
};

Changes

• Strict Namespace Validation: Namespaces defined in the current file (TSModuleDeclaration) are now added to the closedTypes set. This means the rule will strictly validate members accessed on these namespaces (e.g., MyNamespace.NonExistentType will now be reported as undefined).
• Recursive Type Discovery: The rule now recursively finds exported types within namespaces, including:
  • TSTypeAliasDeclaration.
  • TSInterfaceDeclaration (including their properties).
• Test Updates:
  • Added test cases to verify valid access to defined namespace types and interfaces.
  • Added test cases to verify invalid access to undefined namespace types (strict validation).
  • Added a coverage test case to ensure ExportNamedDeclaration variants (like export class and export {}) are properly handled (ignored) without reducing code coverage.

[brettz9]

LGTM! Thanks!

[brettz9]

Actually, your original issue mentions use of the definedTypes option. Can we add a test case to confirm that is not reporting now?

[brettz9]

@risantos : Not sure you saw my last comment?

[risantos]

@brettz9

@risantos : Not sure you saw my last comment?

Sorry, hadn't followed up with notifications since, as I was mostly offline that week.

Actually, your original issue mentions use of the definedTypes option. Can we add a test case to confirm that is not reporting now?

The included tests already cover that scenario, which was the one I was most concerned with. Specifically these lines, where it would report and now passes as expected: https://github.com/gajus/eslint-plugin-jsdoc/pull/1616/changes#diff-743133df9858e36d2a2f4c8de68b9efd79c4637c23b98871fa579124f597ffaaR2050-R2066

[brettz9]

@brettz9

@risantos : Not sure you saw my last comment?

Sorry, hadn't followed up with notifications since, as I was mostly offline that week.

No worries--all good!

Actually, your original issue mentions use of the definedTypes option. Can we add a test case to confirm that is not reporting now?

The included tests already cover that scenario, which was the one I was most concerned with. Specifically these lines, where it would report and now passes as expected: https://github.com/gajus/eslint-plugin-jsdoc/pull/1616/changes#diff-743133df9858e36d2a2f4c8de68b9efd79c4637c23b98871fa579124f597ffaaR2050-R2066

Even if the path is covered, I think it would be good to have your definedTypes example added as one of the test cases.

[risantos]

@brettz9

Even if the path is covered, I think it would be good to have your definedTypes example added as one of the test cases.

Good point, so that the docs make it clear that it'll work if it's part of definedTypes.
I had missed the options, but I've just added the definedTypes on the valid and invalid test scenarios, which should help users understand that the types can be inferred respectively.

Updated and rebased. ✅

[github-actions]

🎉 This PR is included in version 62.2.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀