feat: Implement onUnreachableCodePathStart/End (#17511)

* feat: Implement onUnreachableCodePathStart/End

refs # 17457

* Finish up onUnreachable* work

* Refactor to account for out-of-order events

* Update lib/rules/no-unreachable.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Update lib/rules/no-unreachable.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Update tests/lib/linter/code-path-analysis/code-path-analyzer.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Incorporate feedback

* Clean up rules and docs

* Update docs

* Fix code example

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update lib/rules/consistent-return.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Update lib/rules/no-this-before-super.js

Co-authored-by: Milos Djermanovic <[email protected]>

* Fix examples

* Add deprecation notices to RuleTester/FlatRuleTester

* Update config

* Add deprecation notices to RuleTester/FlatRuleTester

* Fix lint warning

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/extend/code-path-analysis.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Fix test

---------

Co-authored-by: Milos Djermanovic <[email protected]>

Author: nzakas

docs/src/extend/code-path-analysis.md

@@ -226,7 +226,6 @@ module.exports = [
         files: [INTERNAL_FILES.RULE_TESTER_PATTERN],
         rules: {
             "n/no-restricted-require": ["error", [
-                ...createInternalFilesPatterns(INTERNAL_FILES.RULE_TESTER_PATTERN),
                 resolveAbsolutePath("lib/cli-engine/index.js")
             ]]
         }

eslint.config.js

@@ -192,15 +192,18 @@ function forwardCurrentToHead(analyzer, node) {
         headSegment = headSegments[i];
 
         if (currentSegment !== headSegment && currentSegment) {
-            debug.dump(`onCodePathSegmentEnd ${currentSegment.id}`);
 
-            if (currentSegment.reachable) {
-                analyzer.emitter.emit(
-                    "onCodePathSegmentEnd",
-                    currentSegment,
-                    node
-                );
-            }
+            const eventName = currentSegment.reachable
+                ? "onCodePathSegmentEnd"
+                : "onUnreachableCodePathSegmentEnd";
+
+            debug.dump(`${eventName} ${currentSegment.id}`);
+
+            analyzer.emitter.emit(
+                eventName,
+                currentSegment,
+                node
+            );
         }
     }
 
@@ -213,16 +216,19 @@ function forwardCurrentToHead(analyzer, node) {
         headSegment = headSegments[i];
 
         if (currentSegment !== headSegment && headSegment) {
-            debug.dump(`onCodePathSegmentStart ${headSegment.id}`);
+
+            const eventName = headSegment.reachable
+                ? "onCodePathSegmentStart"
+                : "onUnreachableCodePathSegmentStart";
+
+            debug.dump(`${eventName} ${headSegment.id}`);
 
             CodePathSegment.markUsed(headSegment);
-            if (headSegment.reachable) {
-                analyzer.emitter.emit(
-                    "onCodePathSegmentStart",
-                    headSegment,
-                    node
-                );
-            }
+            analyzer.emitter.emit(
+                eventName,
+                headSegment,
+                node
+            );
         }
     }
 
@@ -241,15 +247,17 @@ function leaveFromCurrentSegment(analyzer, node) {
 
     for (let i = 0; i < currentSegments.length; ++i) {
         const currentSegment = currentSegments[i];
+        const eventName = currentSegment.reachable
+            ? "onCodePathSegmentEnd"
+            : "onUnreachableCodePathSegmentEnd";
 
-        debug.dump(`onCodePathSegmentEnd ${currentSegment.id}`);
-        if (currentSegment.reachable) {
-            analyzer.emitter.emit(
-                "onCodePathSegmentEnd",
-                currentSegment,
-                node
-            );
-        }
+        debug.dump(`${eventName} ${currentSegment.id}`);
+
+        analyzer.emitter.emit(
+            eventName,
+            currentSegment,
+            node
+        );
     }
 
     state.currentSegments = [];

lib/linter/code-path-analysis/code-path-analyzer.js

@@ -117,6 +117,7 @@ class CodePath {
     /**
      * Current code path segments.
      * @type {CodePathSegment[]}
+     * @deprecated
      */
     get currentSegments() {
         return this.internal.currentSegments;

lib/linter/code-path-analysis/code-path.js

@@ -898,6 +898,7 @@ const DEPRECATED_SOURCECODE_PASSTHROUGHS = {
     getTokensBetween: "getTokensBetween"
 };
 
+
 const BASE_TRAVERSAL_CONTEXT = Object.freeze(
     Object.keys(DEPRECATED_SOURCECODE_PASSTHROUGHS).reduce(
         (contextInfo, methodName) =>

lib/linter/linter.js

@@ -16,7 +16,9 @@ const
     equal = require("fast-deep-equal"),
     Traverser = require("../shared/traverser"),
     { getRuleOptionsSchema } = require("../config/flat-config-helpers"),
-    { Linter, SourceCodeFixer, interpolate } = require("../linter");
+    { Linter, SourceCodeFixer, interpolate } = require("../linter"),
+    CodePath = require("../linter/code-path-analysis/code-path");
+
 const { FlatConfigArray } = require("../config/flat-config-array");
 const { defaultConfig } = require("../config/default-config");
 
@@ -274,6 +276,21 @@ function getCommentsDeprecation() {
     );
 }
 
+/**
+ * Emit a deprecation warning if rule uses CodePath#currentSegments.
+ * @param {string} ruleName Name of the rule.
+ * @returns {void}
+ */
+function emitCodePathCurrentSegmentsWarning(ruleName) {
+    if (!emitCodePathCurrentSegmentsWarning[`warned-${ruleName}`]) {
+        emitCodePathCurrentSegmentsWarning[`warned-${ruleName}`] = true;
+        process.emitWarning(
+            `"${ruleName}" rule uses CodePath#currentSegments and will stop working in ESLint v9. Please read the documentation for how to update your code: https://eslint.org/docs/latest/extend/code-path-analysis#usage-examples`,
+            "DeprecationWarning"
+        );
+    }
+}
+
 //------------------------------------------------------------------------------
 // Public Interface
 //------------------------------------------------------------------------------
@@ -664,6 +681,7 @@ class FlatRuleTester {
 
             // Verify the code.
             const { getComments } = SourceCode.prototype;
+            const originalCurrentSegments = Object.getOwnPropertyDescriptor(CodePath.prototype, "currentSegments");
             let messages;
 
             // check for validation errors
@@ -677,11 +695,20 @@ class FlatRuleTester {
 
             try {
                 SourceCode.prototype.getComments = getCommentsDeprecation;
+                Object.defineProperty(CodePath.prototype, "currentSegments", {
+                    get() {
+                        emitCodePathCurrentSegmentsWarning(ruleName);
+                        return originalCurrentSegments.get.call(this);
+                    }
+                });
+
                 messages = linter.verify(code, configs, filename);
             } finally {
                 SourceCode.prototype.getComments = getComments;
+                Object.defineProperty(CodePath.prototype, "currentSegments", originalCurrentSegments);
             }
 
+
             const fatalErrorMessage = messages.find(m => m.fatal);
 
             assert(!fatalErrorMessage, `A fatal parsing error occurred: ${fatalErrorMessage && fatalErrorMessage.message}`);

lib/rule-tester/flat-rule-tester.js

@@ -48,7 +48,8 @@ const
     equal = require("fast-deep-equal"),
     Traverser = require("../../lib/shared/traverser"),
     { getRuleOptionsSchema, validate } = require("../shared/config-validator"),
-    { Linter, SourceCodeFixer, interpolate } = require("../linter");
+    { Linter, SourceCodeFixer, interpolate } = require("../linter"),
+    CodePath = require("../linter/code-path-analysis/code-path");
 
 const ajv = require("../shared/ajv")({ strictDefaults: true });
 
@@ -375,6 +376,21 @@ function emitDeprecatedContextMethodWarning(ruleName, methodName) {
     }
 }
 
+/**
+ * Emit a deprecation warning if rule uses CodePath#currentSegments.
+ * @param {string} ruleName Name of the rule.
+ * @returns {void}
+ */
+function emitCodePathCurrentSegmentsWarning(ruleName) {
+    if (!emitCodePathCurrentSegmentsWarning[`warned-${ruleName}`]) {
+        emitCodePathCurrentSegmentsWarning[`warned-${ruleName}`] = true;
+        process.emitWarning(
+            `"${ruleName}" rule uses CodePath#currentSegments and will stop working in ESLint v9. Please read the documentation for how to update your code: https://eslint.org/docs/latest/extend/code-path-analysis#usage-examples`,
+            "DeprecationWarning"
+        );
+    }
+}
+
 //------------------------------------------------------------------------------
 // Public Interface
 //------------------------------------------------------------------------------
@@ -746,13 +762,22 @@ class RuleTester {
 
             // Verify the code.
             const { getComments } = SourceCode.prototype;
+            const originalCurrentSegments = Object.getOwnPropertyDescriptor(CodePath.prototype, "currentSegments");
             let messages;
 
             try {
                 SourceCode.prototype.getComments = getCommentsDeprecation;
+                Object.defineProperty(CodePath.prototype, "currentSegments", {
+                    get() {
+                        emitCodePathCurrentSegmentsWarning(ruleName);
+                        return originalCurrentSegments.get.call(this);
+                    }
+                });
+
                 messages = linter.verify(code, config, filename);
             } finally {
                 SourceCode.prototype.getComments = getComments;
+                Object.defineProperty(CodePath.prototype, "currentSegments", originalCurrentSegments);
             }
 
             const fatalErrorMessage = messages.find(m => m.fatal);

lib/rule-tester/rule-tester.js

@@ -18,15 +18,6 @@ const astUtils = require("./utils/ast-utils");
 const TARGET_NODE_TYPE = /^(?:Arrow)?FunctionExpression$/u;
 const TARGET_METHODS = /^(?:every|filter|find(?:Last)?(?:Index)?|flatMap|forEach|map|reduce(?:Right)?|some|sort|toSorted)$/u;
 
-/**
- * Checks a given code path segment is reachable.
- * @param {CodePathSegment} segment A segment to check.
- * @returns {boolean} `true` if the segment is reachable.
- */
-function isReachable(segment) {
-    return segment.reachable;
-}
-
 /**
  * Checks a given node is a member access which has the specified name's
  * property.
@@ -38,6 +29,22 @@ function isTargetMethod(node) {
     return astUtils.isSpecificMemberAccess(node, null, TARGET_METHODS);
 }
 
+/**
+ * Checks all segments in a set and returns true if any are reachable.
+ * @param {Set<CodePathSegment>} segments The segments to check.
+ * @returns {boolean} True if any segment is reachable; false otherwise.
+ */
+function isAnySegmentReachable(segments) {
+
+    for (const segment of segments) {
+        if (segment.reachable) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 /**
  * Returns a human-legible description of an array method
  * @param {string} arrayMethodName A method name to fully qualify
@@ -205,7 +212,7 @@ module.exports = {
                     messageId = "expectedNoReturnValue";
                 }
             } else {
-                if (node.body.type === "BlockStatement" && funcInfo.codePath.currentSegments.some(isReachable)) {
+                if (node.body.type === "BlockStatement" && isAnySegmentReachable(funcInfo.currentSegments)) {
                     messageId = funcInfo.hasReturn ? "expectedAtEnd" : "expectedInside";
                 }
             }
@@ -242,7 +249,8 @@ module.exports = {
                         methodName &&
                         !node.async &&
                         !node.generator,
-                    node
+                    node,
+                    currentSegments: new Set()
                 };
             },
 
@@ -251,6 +259,23 @@ module.exports = {
                 funcInfo = funcInfo.upper;
             },
 
+            onUnreachableCodePathSegmentStart(segment) {
+                funcInfo.currentSegments.add(segment);
+            },
+
+            onUnreachableCodePathSegmentEnd(segment) {
+                funcInfo.currentSegments.delete(segment);
+            },
+
+            onCodePathSegmentStart(segment) {
+                funcInfo.currentSegments.add(segment);
+            },
+
+            onCodePathSegmentEnd(segment) {
+                funcInfo.currentSegments.delete(segment);
+            },
+
+
             // Checks the return statement is valid.
             ReturnStatement(node) {
 

lib/rules/array-callback-return.js

@@ -16,12 +16,19 @@ const { upperCaseFirst } = require("../shared/string-utils");
 //------------------------------------------------------------------------------
 
 /**
- * Checks whether or not a given code path segment is unreachable.
- * @param {CodePathSegment} segment A CodePathSegment to check.
- * @returns {boolean} `true` if the segment is unreachable.
+ * Checks all segments in a set and returns true if all are unreachable.
+ * @param {Set<CodePathSegment>} segments The segments to check.
+ * @returns {boolean} True if all segments are unreachable; false otherwise.
  */
-function isUnreachable(segment) {
-    return !segment.reachable;
+function areAllSegmentsUnreachable(segments) {
+
+    for (const segment of segments) {
+        if (segment.reachable) {
+            return false;
+        }
+    }
+
+    return true;
 }
 
 /**
@@ -88,7 +95,7 @@ module.exports = {
              * When unreachable, all paths are returned or thrown.
              */
             if (!funcInfo.hasReturnValue ||
-                funcInfo.codePath.currentSegments.every(isUnreachable) ||
+                areAllSegmentsUnreachable(funcInfo.currentSegments) ||
                 astUtils.isES5Constructor(node) ||
                 isClassConstructor(node)
             ) {
@@ -141,13 +148,31 @@ module.exports = {
                     hasReturn: false,
                     hasReturnValue: false,
                     messageId: "",
-                    node
+                    node,
+                    currentSegments: new Set()
                 };
             },
             onCodePathEnd() {
                 funcInfo = funcInfo.upper;
             },
 
+            onUnreachableCodePathSegmentStart(segment) {
+                funcInfo.currentSegments.add(segment);
+            },
+
+            onUnreachableCodePathSegmentEnd(segment) {
+                funcInfo.currentSegments.delete(segment);
+            },
+
+            onCodePathSegmentStart(segment) {
+                funcInfo.currentSegments.add(segment);
+            },
+
+            onCodePathSegmentEnd(segment) {
+                funcInfo.currentSegments.delete(segment);
+            },
+
+
             // Reports a given return statement if it's inconsistent.
             ReturnStatement(node) {
                 const argument = node.argument;