[eslint-plugin-packlets] Add documentation for the "@rushstack/typedef-var" rule

[nvrtmd]

Summary

Hello Rushstack team,

I'd like to ask about the documentation for the @rushstack/typedef-var rule. The rationale comment in _common.js points to the @rushstack/eslint-plugin documentation.

      // RATIONALE:         See the @rushstack/eslint-plugin documentation
      '@rushstack/typedef-var': 'warn',

However, the README.md for the plugin doesn't seem to mention the @rushstack/typedef-var rule. Is there a specific reason for this omission?

Details

This question arose from some confusion during a code review on my team. Our ESLint config extends Rushstack's and includes the following override:

/**
 * RATIONALE : Enforcing type definitions where type inference is sufficient
 * docs: https://typescript-eslint.io/rules/typedef/
 */
'@rushstack/typedef-var': 'off',

When I followed the docs link, I found that the @typescript-eslint/typedef rule is deprecated. This led me to wonder if @rushstack/typedef-var was also deprecated and should be removed from our codebase.

Since the explanation of this rule wasn't in the README, I had to investigate the source code. From my analysis of typedef-var.ts, I came to the following understanding:

The @rushstack/typedef-var rule is a custom supplement to @typescript-eslint/typedef. It enforces Rushstack's philosophy of "readability over writability" by requiring explicit types for top-level variables (the "public API" of a file), while intentionally ignoring local variables inside functions and methods.

This distinction is very important, but currently not discoverable without reading the source code.

Proposal

If my understanding is correct, I would love the opportunity to contribute by adding a section for @rushstack/typedef-var to the eslint-plugin README.md.

This would greatly help users like me to:

• Understand the difference between @typescript-eslint/typedef and @rushstack/typedef-var.
• Grasp the rationale behind Rushstack's specific implementation.
• Avoid the confusion I experienced.

Please let me know if my analysis is correct or not and if a PR for this would be welcome. Thank you!

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@rushstack/eslint-plugin-packlets version?
Operating system?
Would you consider contributing a PR?	Yes 🙌
TypeScript compiler version?
Node.js version (node -v)?

[octogonz]

@nvrtmd thanks for this feedback.

Feel free to create a PR to update the README.md with better explanations!

Actually, we had plans to create an entire subsite https://lint.rushstack.io that would provide a "style guide" based around these rules. (The companies I've worked that use Rush Stack's rules each have their own internal wiki docs to this effect, but it would be great to make it public and standardized.) I just never got around to setting it up.

If you are good at technical writing and want to get involved with something deeper like this, let us know. (Chat on Zulip or BlueSky often usually faster than GitHub issues.)

[nvrtmd]

If you are good at technical writing and want to get involved with something deeper like this, let us know. (Chat on Zulip or BlueSky often usually faster than GitHub issues.)

@octogonz Thank you for the response and the warm welcome.

I am enthusiastic about contributing to open source, and I am especially excited about the potential to help document and define Rushstack's standards. I truly appreciate the opportunity to contribute.

I will prioritize this task I raised and aim to submit the Pull Request by the end of this month, or sooner.

Once the PR has been submitted, I will reach out via Zulip or BlueSky to follow up and express my interest in getting involved with the style guide project you mentioned, should my contribution prove sufficient.

Thank you again for your time and guidance!