feat: add no-unassigned-vars rule (#19618)

jtbandes · Tanujkanti4441 · kirkwaiblinger · web-flow · commit 7bc6c71ca350 · 2025-05-07T10:31:07.000-04:00
* feat: add no-unassigned-vars rule * Apply suggestions from code review Co-authored-by: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com> Co-authored-by: Kirk Waiblinger <53019676+kirkwaiblinger@users.noreply.github.com> * add typescript examples * Update docs/src/rules/no-unassigned-vars.md Co-authored-by: Nitin Kumar <snitin315@gmail.com> * review feedback * more review feedback * Apply suggestions from code review Co-authored-by: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com> * npm run build:site * fix missing directive * review feedback * review feedback * add no-unused-vars to related_rules and add back-links from all related rules * review feedback * add When Not To Use It per @snitin315 feedback --------- Co-authored-by: Tanuj Kanti <86398394+Tanujkanti4441@users.noreply.github.com> Co-authored-by: Kirk Waiblinger <53019676+kirkwaiblinger@users.noreply.github.com> Co-authored-by: Nitin Kumar <snitin315@gmail.com>
diff --git a/docs/src/_data/rules.json b/docs/src/_data/rules.json
@@ -337,6 +337,14 @@
                 "frozen": false,
                 "hasSuggestions": false
             },
+            {
+                "name": "no-unassigned-vars",
+                "description": "Disallow `let` or `var` variables that are read but never assigned",
+                "recommended": false,
+                "fixable": false,
+                "frozen": false,
+                "hasSuggestions": false
+            },
             {
                 "name": "no-undef",
                 "description": "Disallow the use of undeclared variables unless mentioned in `/*global */` comments",
diff --git a/docs/src/_data/rules_meta.json b/docs/src/_data/rules_meta.json
@@ -3260,6 +3260,19 @@
         },
         "fixable": "whitespace"
     },
+    "no-unassigned-vars": {
+        "type": "problem",
+        "dialects": [
+            "typescript",
+            "javascript"
+        ],
+        "language": "javascript",
+        "docs": {
+            "description": "Disallow `let` or `var` variables that are read but never assigned",
+            "recommended": false,
+            "url": "https://eslint.org/docs/latest/rules/no-unassigned-vars"
+        }
+    },
     "no-undef": {
         "type": "problem",
         "defaultOptions": [
diff --git a/docs/src/rules/init-declarations.md b/docs/src/rules/init-declarations.md
@@ -1,6 +1,8 @@
 ---
 title: init-declarations
 rule_type: suggestion
+related_rules:
+- no-unassigned-vars
 ---
 
 
diff --git a/docs/src/rules/no-unassigned-vars.md b/docs/src/rules/no-unassigned-vars.md
@@ -0,0 +1,141 @@
+---
+title: no-unassigned-vars
+rule_type: problem
+related_rules:
+- init-declarations
+- no-unused-vars
+- prefer-const
+---
+
+
+This rule flags `let` or `var` declarations that are never assigned a value but are still read or used in the code. Since these variables will always be `undefined`, their usage is likely a programming mistake.
+
+For example, if you check the value of a `status` variable, but it was never given a value, it will always be `undefined`:
+
+```js
+let status;
+
+// ...forgot to assign a value to status...
+
+if (status === 'ready') {
+  console.log('Ready!');
+}
+```
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+::: incorrect
+
+```js
+/*eslint no-unassigned-vars: "error"*/
+
+let status;
+if (status === 'ready') {
+  console.log('Ready!');
+}
+
+let user;
+greet(user);
+
+function test() {
+  let error;
+  return error || "Unknown error";
+}
+
+let options;
+const { debug } = options || {};
+
+let flag;
+while (!flag) {
+  // Do something...
+}
+
+let config;
+function init() {
+  return config?.enabled;
+}
+```
+
+:::
+
+In TypeScript:
+
+::: incorrect
+
+```ts
+/*eslint no-unassigned-vars: "error"*/
+
+let value: number | undefined;
+console.log(value);
+```
+
+:::
+
+Examples of **correct** code for this rule:
+
+::: correct
+
+```js
+/*eslint no-unassigned-vars: "error"*/
+
+let message = "hello";
+console.log(message);
+
+let user;
+user = getUser();
+console.log(user.name);
+
+let count;
+count = 1;
+count++;
+
+// Variable is unused (should be reported by `no-unused-vars` only)
+let temp;
+
+let error;
+if (somethingWentWrong) {
+  error = "Something went wrong";
+}
+console.log(error);
+
+let item;
+for (item of items) {
+  process(item);
+}
+
+let config;
+function setup() {
+  config = { debug: true };
+}
+setup();
+console.log(config);
+
+let one = undefined;
+if (one === two) {
+  // Noop
+}
+```
+
+:::
+
+In TypeScript:
+
+::: correct
+
+```ts
+/*eslint no-unassigned-vars: "error"*/
+
+declare let value: number | undefined;
+console.log(value);
+```
+
+:::
+
+## When Not To Use It
+
+You can disable this rule if your code intentionally uses variables that are declared and used, but are never assigned a value. This might be the case in:
+
+- Legacy codebases where uninitialized variables are used as placeholders.
+- Certain TypeScript use cases where variables are declared with a type and intentionally left unassigned (though using `declare` is preferred).
diff --git a/docs/src/rules/no-unused-vars.md b/docs/src/rules/no-unused-vars.md
@@ -2,6 +2,7 @@
 title: no-unused-vars
 rule_type: problem
 related_rules:
+- no-unassigned-vars
 - no-useless-assignment
 ---
 
diff --git a/docs/src/rules/prefer-const.md b/docs/src/rules/prefer-const.md
@@ -3,6 +3,7 @@ title: prefer-const
 rule_type: suggestion
 related_rules:
 - no-var
+- no-unassigned-vars
 - no-use-before-define
 ---
 
diff --git a/lib/rules/index.js b/lib/rules/index.js
@@ -225,6 +225,7 @@ module.exports = new LazyLoadingRuleMap(
 		"no-this-before-super": () => require("./no-this-before-super"),
 		"no-throw-literal": () => require("./no-throw-literal"),
 		"no-trailing-spaces": () => require("./no-trailing-spaces"),
+		"no-unassigned-vars": () => require("./no-unassigned-vars"),
 		"no-undef": () => require("./no-undef"),
 		"no-undef-init": () => require("./no-undef-init"),
 		"no-undefined": () => require("./no-undefined"),
diff --git a/lib/rules/no-unassigned-vars.js b/lib/rules/no-unassigned-vars.js
@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Rule to flag variables that are never assigned
+ * @author Jacob Bandes-Storch <https://github.com/jtbandes>
+ */
+"use strict";
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+/** @type {import('../types').Rule.RuleModule} */
+module.exports = {
+	meta: {
+		type: "problem",
+		dialects: ["typescript", "javascript"],
+		language: "javascript",
+
+		docs: {
+			description:
+				"Disallow `let` or `var` variables that are read but never assigned",
+			recommended: false,
+			url: "https://eslint.org/docs/latest/rules/no-unassigned-vars",
+		},
+
+		schema: [],
+		messages: {
+			unassigned:
+				"'{{name}}' is always 'undefined' because it's never assigned.",
+		},
+	},
+
+	create(context) {
+		const sourceCode = context.sourceCode;
+
+		return {
+			VariableDeclarator(node) {
+				/** @type {import('estree').VariableDeclaration} */
+				const declaration = node.parent;
+				const shouldCheck =
+					!node.init &&
+					node.id.type === "Identifier" &&
+					declaration.kind !== "const" &&
+					!declaration.declare;
+				if (!shouldCheck) {
+					return;
+				}
+				const [variable] = sourceCode.getDeclaredVariables(node);
+				if (!variable) {
+					return;
+				}
+				let hasRead = false;
+				for (const reference of variable.references) {
+					if (reference.isWrite()) {
+						return;
+					}
+					if (reference.isRead()) {
+						hasRead = true;
+					}
+				}
+				if (!hasRead) {
+					// Variables that are never read should be flagged by no-unused-vars instead
+					return;
+				}
+				context.report({
+					node,
+					messageId: "unassigned",
+					data: { name: node.id.name },
+				});
+			},
+		};
+	},
+};
diff --git a/lib/types/rules.d.ts b/lib/types/rules.d.ts
@@ -3714,6 +3714,13 @@ export interface ESLintRules extends Linter.RulesRecord {
 		]
 	>;
 
+	/**
+	 * Rule to disallow `let` or `var` variables that are read but never assigned.
+	 *
+	 * @see https://eslint.org/docs/latest/rules/no-unassigned-vars
+	 */
+	"no-unassigned-vars": Linter.RuleEntry<[]>;
+
 	/**
 	 * Rule to disallow the use of undeclared variables unless mentioned in \/*global *\/ comments.
 	 *
diff --git a/packages/eslint-config-eslint/base.js b/packages/eslint-config-eslint/base.js
@@ -88,6 +88,7 @@ const jsConfigs = [
 			"no-sequences": "error",
 			"no-shadow": "error",
 			"no-throw-literal": "error",
+			"no-unassigned-vars": "error",
 			"no-undef": ["error", { typeof: true }],
 			"no-undef-init": "error",
 			"no-undefined": "error",
diff --git a/packages/js/src/configs/eslint-all.js b/packages/js/src/configs/eslint-all.js
@@ -149,6 +149,7 @@ module.exports = Object.freeze({
         "no-ternary": "error",
         "no-this-before-super": "error",
         "no-throw-literal": "error",
+        "no-unassigned-vars": "error",
         "no-undef": "error",
         "no-undef-init": "error",
         "no-undefined": "error",
diff --git a/tests/lib/rules/no-unassigned-vars.js b/tests/lib/rules/no-unassigned-vars.js

Original file line number	Diff line number	Diff line change
`@@ -3714,6 +3714,13 @@ export interface ESLintRules extends Linter.RulesRecord {`
`3714`	`3714`	`]`
`3715`	`3715`	`>;`
`3716`	`3716`
	`3717`	`+ /**`
	`3718`	+ * Rule to disallow `let` or `var` variables that are read but never assigned.
	`3719`	`+ *`
	`3720`	`+ * @see https://eslint.org/docs/latest/rules/no-unassigned-vars`
	`3721`	`+ */`
	`3722`	`+ "no-unassigned-vars": Linter.RuleEntry<[]>;`
	`3723`	`+`
`3717`	`3724`	`/**`
`3718`	`3725`	`* Rule to disallow the use of undeclared variables unless mentioned in \/global \/ comments.`
`3719`	`3726`	`*`