From 13f6cb5cb06d8d1b8ab6c5a1a43905ee37fa2047 Mon Sep 17 00:00:00 2001
From: yuza <67324487+nvrtmd@users.noreply.github.com>
Date: Thu, 9 Oct 2025 21:28:56 +0900
Subject: [PATCH 1/3] docs(eslint-plugin): document the @rushstack/typedef-var
 rule

---
 eslint/eslint-plugin/README.md | 80 ++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/eslint/eslint-plugin/README.md b/eslint/eslint-plugin/README.md
index bc6acc39f87..dc5e9fb08be 100644
--- a/eslint/eslint-plugin/README.md
+++ b/eslint/eslint-plugin/README.md
@@ -55,6 +55,86 @@ let y: typeof import('./file');
 jest.mock('./file'); // okay
 ```
 
+## `@rushstack/typedef-var`
+
+Require explicit type annotations for top-level variable declarations, while exempting local variables within function or method scopes.
+
+#### Rule Details
+
+This rule is implemented to supplement the deprecated `@typescript-eslint/typedef` rule. The `@typescript-eslint/typedef` rule was deprecated based on the judgment that "unnecessary type annotations, where type inference is sufficient, can be cumbersome to maintain and generally reduce code readability."
+
+However, we prioritize code reading and maintenance over code authorship. That is, even when the compiler can infer a type, this rule enforces explicit type annotations to ensure that a code reviewer (e.g., when viewing a GitHub Diff) does not have to rely entirely on inference and can immediately ascertain a variable's type. This approach makes writing code harder but significantly improves the more crucial activity of reading and reviewing code.
+
+Therefore, the `@rushstack/typedef-var` rule enforces type annotations for all variable declarations outside of local function or class method scopes. This includes the module's top-level scope and any block scopes that do not belong to a function or method.
+
+To balance this strictness with code authoring convenience, the rule deliberately relaxes the type annotation requirement for the following local variable declarations:
+
+- Variable declarations within a function body.
+- Variable declarations within a class method.
+- Variables used in the declaration part of `for...of` or `for...in` statements.
+- Variables declared via object or array destructuring assignments.
+
+#### Examples
+
+The following patterns are considered problems when `@rushstack/typedef-var` is enabled:
+
+```ts
+// Top-level declarations lack explicit type annotations
+const x = 123; // error
+
+let x = 123; // error
+
+var x = 123; // error
+```
+
+```ts
+// Declaration within a non-function block scope
+{
+  const x = 123; // error
+}
+```
+
+The following patterns are NOT considered problems:
+
+```ts
+// Local variables inside function expressions are exempt
+function f() { const x = 123; } // passes
+
+const f = () => { const x = 123; }; // passes
+
+const f = function() { const x = 123; } // passes
+```
+
+```ts
+// Local variables inside class methods are exempt
+class C {
+  public m(): void {
+    const x = 123; // passes
+  }
+}
+
+class C {
+  public m = (): void => {
+    const x = 123; // passes
+  }
+}
+```
+
+```ts
+// Variables in for...of and for...in declarations are exempt
+for (const x of []) { }  // passes
+
+for (const x in []) { } // passes
+```
+
+```ts
+// Array and Object Destructuring assignments are exempt
+let { a, b } = { // passes
+  a: 123,
+  b: 234
+}
+```
+
 ## `@rushstack/no-new-null`
 
 Prevent usage of the JavaScript `null` value, while allowing code to access existing APIs that

From c925bb0bdbb0b50f12e15d15761b79ea84e9e49d Mon Sep 17 00:00:00 2001
From: yuza <67324487+nvrtmd@users.noreply.github.com>
Date: Thu, 9 Oct 2025 21:46:47 +0900
Subject: [PATCH 2/3] chore(changefile): add changefile for typedef-var
 documentation

---
 ...docs-explain-typedef-var-rule_2025-10-09-12-46.json | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 common/changes/@rushstack/eslint-plugin/docs-explain-typedef-var-rule_2025-10-09-12-46.json

diff --git a/common/changes/@rushstack/eslint-plugin/docs-explain-typedef-var-rule_2025-10-09-12-46.json b/common/changes/@rushstack/eslint-plugin/docs-explain-typedef-var-rule_2025-10-09-12-46.json
new file mode 100644
index 00000000000..5ea1dcf9bdb
--- /dev/null
+++ b/common/changes/@rushstack/eslint-plugin/docs-explain-typedef-var-rule_2025-10-09-12-46.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/eslint-plugin",
+      "comment": "Added documentation for the @rushstack/typedef-var ESLint rule. This clarifies the rule's rationale (readability over writability) and explicitly lists all local variable exemptions, resolving confusion around its usage.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/eslint-plugin"
+}
\ No newline at end of file

From 768345bc690a0aded6eea48391ba7fa8d4f7e5cf Mon Sep 17 00:00:00 2001
From: yuza <67324487+nvrtmd@users.noreply.github.com>
Date: Thu, 9 Oct 2025 23:21:15 +0900
Subject: [PATCH 3/3] docs: remove for...of and for...in exception from
 typedef-var rule documentation

---
 eslint/eslint-plugin/README.md | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/eslint/eslint-plugin/README.md b/eslint/eslint-plugin/README.md
index dc5e9fb08be..0e920881e40 100644
--- a/eslint/eslint-plugin/README.md
+++ b/eslint/eslint-plugin/README.md
@@ -71,7 +71,6 @@ To balance this strictness with code authoring convenience, the rule deliberatel
 
 - Variable declarations within a function body.
 - Variable declarations within a class method.
-- Variables used in the declaration part of `for...of` or `for...in` statements.
 - Variables declared via object or array destructuring assignments.
 
 #### Examples
@@ -120,13 +119,6 @@ class C {
 }
 ```
 
-```ts
-// Variables in for...of and for...in declarations are exempt
-for (const x of []) { }  // passes
-
-for (const x in []) { } // passes
-```
-
 ```ts
 // Array and Object Destructuring assignments are exempt
 let { a, b } = { // passes