[eslint-plugin] Document the @rushstack/typedef-var rule and clarify scope

[nvrtmd]

Summary

This PR resolves user confusion regarding the existence and scope of the @rushstack/typedef-var ESLint rule. Although the rule is referenced in the ESLint config rationale, it was missing from the plugin's README, leading users (as documented in Issue #5374) to question its deprecation status.

I have added comprehensive documentation to the eslint/eslint-plugin/README.md file. The new section clarifies the rule's strict philosophy ("reading over writing") and explicitly defines the exact local scope exemptions.

Fixes #5374

Details

Problem Solved:
The primary problem was the lack of documentation, which prevented users from understanding the core difference between @typescript-eslint/typedef (deprecated) and @rushstack/typedef-var (active).

How it was solved:
I analyzed the typedef-var.ts and typedef-var.test.ts source files to reverse-engineer the exact scope of the rule. The new documentation section includes:

1. Rationale: The Rushstack philosophy that "writing code is a less important activity than reading it."(reference)
2. Scope Enforcement: Explicitly states the rule enforces types for declarations outside of local function/method scopes.
3. Exemptions: Lists all four local variable exemptions (functions, methods, for...of/for...in, destructuring) supported by the existing code.

Consistency Question & Follow-up (Nontrivial Change):
During analysis, a potential design inconsistency was noted which I am currently seeking clarification on in the #contributor-helpline:

• The rule explicitly exempts for...of and for...in variables, but testing reveals that standard for loop variables (e.g., for (var x = 0; x < 10; x++)) are NOT exempted and require a type annotation.

If this strictness on standard for loops is confirmed to be the intentional design, I propose submitting a follow-up PR to add an explicit failing test case to typedef-var.test.ts to ensure this behavior is covered and prevents future regressions.

How it was tested

Impacted documentation

The core documentation for the @rushstack/eslint-plugin package is impacted:

• https://github.com/microsoft/rushstack/blob/main/eslint/eslint-plugin/README.md

[nvrtmd]

@microsoft-github-policy-service agree