eslint 8.50.0 → 8.52.0

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

@@ -80,7 +80,9 @@ class CodePath {
     }
 
     /**
-     * The initial code path segment.
+     * The initial code path segment. This is the segment that is at the head
+     * of the code path.
+     * This is a passthrough to the underlying `CodePathState`.
      * @type {CodePathSegment}
      */
     get initialSegment() {
@@ -88,8 +90,10 @@ class CodePath {
     }
 
     /**
-     * Final code path segments.
-     * This array is a mix of `returnedSegments` and `thrownSegments`.
+     * Final code path segments. These are the terminal (tail) segments in the
+     * code path, which is the combination of `returnedSegments` and `thrownSegments`.
+     * All segments in this array are reachable.
+     * This is a passthrough to the underlying `CodePathState`.
      * @type {CodePathSegment[]}
      */
     get finalSegments() {
@@ -97,9 +101,14 @@ class CodePath {
     }
 
     /**
-     * Final code path segments which is with `return` statements.
-     * This array contains the last path segment if it's reachable.
-     * Since the reachable last path returns `undefined`.
+     * Final code path segments that represent normal completion of the code path.
+     * For functions, this means both explicit `return` statements and implicit returns,
+     * such as the last reachable segment in a function that does not have an
+     * explicit `return` as this implicitly returns `undefined`. For scripts,
+     * modules, class field initializers, and class static blocks, this means
+     * all lines of code have been executed.
+     * These segments are also present in `finalSegments`.
+     * This is a passthrough to the underlying `CodePathState`.
      * @type {CodePathSegment[]}
      */
     get returnedSegments() {
@@ -107,7 +116,9 @@ class CodePath {
     }
 
     /**
-     * Final code path segments which is with `throw` statements.
+     * Final code path segments that represent `throw` statements.
+     * This is a passthrough to the underlying `CodePathState`.
+     * These segments are also present in `finalSegments`.
      * @type {CodePathSegment[]}
      */
     get thrownSegments() {
@@ -115,7 +126,12 @@ class CodePath {
     }
 
     /**
-     * Current code path segments.
+     * Tracks the traversal of the code path through each segment. This array
+     * starts empty and segments are added or removed as the code path is
+     * traversed. This array always ends up empty at the end of a code path
+     * traversal. The `CodePathState` uses this to track its progress through
+     * the code path.
+     * This is a passthrough to the underlying `CodePathState`.
      * @type {CodePathSegment[]}
      * @deprecated
      */
@@ -126,46 +142,70 @@ class CodePath {
     /**
      * Traverses all segments in this code path.
      *
-     *     codePath.traverseSegments(function(segment, controller) {
+     *     codePath.traverseSegments((segment, controller) => {
      *         // do something.
      *     });
      *
      * This method enumerates segments in order from the head.
      *
-     * The `controller` object has two methods.
+     * The `controller` argument has two methods:
      *
-     * - `controller.skip()` - Skip the following segments in this branch.
-     * - `controller.break()` - Skip all following segments.
-     * @param {Object} [options] Omittable.
-     * @param {CodePathSegment} [options.first] The first segment to traverse.
-     * @param {CodePathSegment} [options.last] The last segment to traverse.
+     * - `skip()` - skips the following segments in this branch
+     * - `break()` - skips all following segments in the traversal
+     *
+     * A note on the parameters: the `options` argument is optional. This means
+     * the first argument might be an options object or the callback function.
+     * @param {Object} [optionsOrCallback] Optional first and last segments to traverse.
+     * @param {CodePathSegment} [optionsOrCallback.first] The first segment to traverse.
+     * @param {CodePathSegment} [optionsOrCallback.last] The last segment to traverse.
      * @param {Function} callback A callback function.
      * @returns {void}
      */
-    traverseSegments(options, callback) {
+    traverseSegments(optionsOrCallback, callback) {
+
+        // normalize the arguments into a callback and options
         let resolvedOptions;
         let resolvedCallback;
 
-        if (typeof options === "function") {
-            resolvedCallback = options;
+        if (typeof optionsOrCallback === "function") {
+            resolvedCallback = optionsOrCallback;
             resolvedOptions = {};
         } else {
-            resolvedOptions = options || {};
+            resolvedOptions = optionsOrCallback || {};
             resolvedCallback = callback;
         }
 
+        // determine where to start traversing from based on the options
         const startSegment = resolvedOptions.first || this.internal.initialSegment;
         const lastSegment = resolvedOptions.last;
 
-        let item = null;
+        // set up initial location information
+        let record = null;
         let index = 0;
         let end = 0;
         let segment = null;
-        const visited = Object.create(null);
+
+        // segments that have already been visited during traversal
+        const visited = new Set();
+
+        // tracks the traversal steps
         const stack = [[startSegment, 0]];
+
+        // tracks the last skipped segment during traversal
         let skippedSegment = null;
+
+        // indicates if we exited early from the traversal
         let broken = false;
+
+        /**
+         * Maintains traversal state.
+         */
         const controller = {
+
+            /**
+             * Skip the following segments in this branch.
+             * @returns {void}
+             */
             skip() {
                 if (stack.length <= 1) {
                     broken = true;
@@ -173,32 +213,52 @@ class CodePath {
                     skippedSegment = stack[stack.length - 2][0];
                 }
             },
+
+            /**
+             * Stop traversal completely - do not traverse to any
+             * other segments.
+             * @returns {void}
+             */
             break() {
                 broken = true;
             }
         };
 
         /**
-         * Checks a given previous segment has been visited.
+         * Checks if a given previous segment has been visited.
          * @param {CodePathSegment} prevSegment A previous segment to check.
          * @returns {boolean} `true` if the segment has been visited.
          */
         function isVisited(prevSegment) {
             return (
-                visited[prevSegment.id] ||
+                visited.has(prevSegment) ||
                 segment.isLoopedPrevSegment(prevSegment)
             );
         }
 
+        // the traversal
         while (stack.length > 0) {
-            item = stack[stack.length - 1];
-            segment = item[0];
-            index = item[1];
+
+            /*
+             * This isn't a pure stack. We use the top record all the time
+             * but don't always pop it off. The record is popped only if
+             * one of the following is true:
+             *
+             * 1) We have already visited the segment.
+             * 2) We have not visited *all* of the previous segments.
+             * 3) We have traversed past the available next segments.
+             *
+             * Otherwise, we just read the value and sometimes modify the
+             * record as we traverse.
+             */
+            record = stack[stack.length - 1];
+            segment = record[0];
+            index = record[1];
 
             if (index === 0) {
 
                 // Skip if this segment has been visited already.
-                if (visited[segment.id]) {
+                if (visited.has(segment)) {
                     stack.pop();
                     continue;
                 }
@@ -212,18 +272,29 @@ class CodePath {
                     continue;
                 }
 
-                // Reset the flag of skipping if all branches have been skipped.
+                // Reset the skipping flag if all branches have been skipped.
                 if (skippedSegment && segment.prevSegments.includes(skippedSegment)) {
                     skippedSegment = null;
                 }
-                visited[segment.id] = true;
+                visited.add(segment);
 
-                // Call the callback when the first time.
+                /*
+                 * If the most recent segment hasn't been skipped, then we call
+                 * the callback, passing in the segment and the controller.
+                 */
                 if (!skippedSegment) {
                     resolvedCallback.call(this, segment, controller);
+
+                    // exit if we're at the last segment
                     if (segment === lastSegment) {
                         controller.skip();
                     }
+
+                    /*
+                     * If the previous statement was executed, or if the callback
+                     * called a method on the controller, we might need to exit the
+                     * loop, so check for that and break accordingly.
+                     */
                     if (broken) {
                         break;
                     }
@@ -233,12 +304,35 @@ class CodePath {
             // Update the stack.
             end = segment.nextSegments.length - 1;
             if (index < end) {
-                item[1] += 1;
+
+                /*
+                 * If we haven't yet visited all of the next segments, update
+                 * the current top record on the stack to the next index to visit
+                 * and then push a record for the current segment on top.
+                 *
+                 * Setting the current top record's index lets us know how many
+                 * times we've been here and ensures that the segment won't be
+                 * reprocessed (because we only process segments with an index
+                 * of 0).
+                 */
+                record[1] += 1;
                 stack.push([segment.nextSegments[index], 0]);
             } else if (index === end) {
-                item[0] = segment.nextSegments[index];
-                item[1] = 0;
+
+                /*
+                 * If we are at the last next segment, then reset the top record
+                 * in the stack to next segment and set its index to 0 so it will
+                 * be processed next.
+                 */
+                record[0] = segment.nextSegments[index];
+                record[1] = 0;
             } else {
+
+                /*
+                 * If index > end, that means we have no more segments that need
+                 * processing. So, we pop that record off of the stack in order to
+                 * continue traversing at the next level up.
+                 */
                 stack.pop();
             }
         }

package/lib/linter/code-path-analysis/fork-context.js

@@ -21,8 +21,8 @@ const assert = require("assert"),
 //------------------------------------------------------------------------------
 
 /**
- * Gets whether or not a given segment is reachable.
- * @param {CodePathSegment} segment A segment to get.
+ * Determines whether or not a given segment is reachable.
+ * @param {CodePathSegment} segment The segment to check.
  * @returns {boolean} `true` if the segment is reachable.
  */
 function isReachable(segment) {
@@ -30,32 +30,64 @@ function isReachable(segment) {
 }
 
 /**
- * Creates new segments from the specific range of `context.segmentsList`.
+ * Creates a new segment for each fork in the given context and appends it
+ * to the end of the specified range of segments. Ultimately, this ends up calling
+ * `new CodePathSegment()` for each of the forks using the `create` argument
+ * as a wrapper around special behavior.
+ *
+ * The `startIndex` and `endIndex` arguments specify a range of segments in
+ * `context` that should become `allPrevSegments` for the newly created
+ * `CodePathSegment` objects.
  *
  * When `context.segmentsList` is `[[a, b], [c, d], [e, f]]`, `begin` is `0`, and
- * `end` is `-1`, this creates `[g, h]`. This `g` is from `a`, `c`, and `e`.
- * This `h` is from `b`, `d`, and `f`.
- * @param {ForkContext} context An instance.
- * @param {number} begin The first index of the previous segments.
- * @param {number} end The last index of the previous segments.
- * @param {Function} create A factory function of new segments.
- * @returns {CodePathSegment[]} New segments.
+ * `end` is `-1`, this creates two new segments, `[g, h]`. This `g` is appended to
+ * the end of the path from `a`, `c`, and `e`. This `h` is appended to the end of
+ * `b`, `d`, and `f`.
+ * @param {ForkContext} context An instance from which the previous segments
+ *      will be obtained.
+ * @param {number} startIndex The index of the first segment in the context
+ *      that should be specified as previous segments for the newly created segments.
+ * @param {number} endIndex The index of the last segment in the context
+ *      that should be specified as previous segments for the newly created segments.
+ * @param {Function} create A function that creates new `CodePathSegment`
+ *      instances in a particular way. See the `CodePathSegment.new*` methods.
+ * @returns {Array<CodePathSegment>} An array of the newly-created segments.
  */
-function makeSegments(context, begin, end, create) {
+function createSegments(context, startIndex, endIndex, create) {
+
+    /** @type {Array<Array<CodePathSegment>>} */
     const list = context.segmentsList;
 
-    const normalizedBegin = begin >= 0 ? begin : list.length + begin;
-    const normalizedEnd = end >= 0 ? end : list.length + end;
+    /*
+     * Both `startIndex` and `endIndex` work the same way: if the number is zero
+     * or more, then the number is used as-is. If the number is negative,
+     * then that number is added to the length of the segments list to
+     * determine the index to use. That means -1 for either argument
+     * is the last element, -2 is the second to last, and so on.
+     *
+     * So if `startIndex` is 0, `endIndex` is -1, and `list.length` is 3, the
+     * effective `startIndex` is 0 and the effective `endIndex` is 2, so this function
+     * will include items at indices 0, 1, and 2.
+     *
+     * Therefore, if `startIndex` is -1 and `endIndex` is -1, that means we'll only
+     * be using the last segment in `list`.
+     */
+    const normalizedBegin = startIndex >= 0 ? startIndex : list.length + startIndex;
+    const normalizedEnd = endIndex >= 0 ? endIndex : list.length + endIndex;
 
+    /** @type {Array<CodePathSegment>} */
     const segments = [];
 
     for (let i = 0; i < context.count; ++i) {
+
+        // this is passed into `new CodePathSegment` to add to code path.
         const allPrevSegments = [];
 
         for (let j = normalizedBegin; j <= normalizedEnd; ++j) {
             allPrevSegments.push(list[j][i]);
         }
 
+        // note: `create` is just a wrapper that augments `new CodePathSegment`.
         segments.push(create(context.idGenerator.next(), allPrevSegments));
     }
 
@@ -63,28 +95,57 @@ function makeSegments(context, begin, end, create) {
 }
 
 /**
- * `segments` becomes doubly in a `finally` block. Then if a code path exits by a
- * control statement (such as `break`, `continue`) from the `finally` block, the
- * destination's segments may be half of the source segments. In that case, this
- * merges segments.
- * @param {ForkContext} context An instance.
- * @param {CodePathSegment[]} segments Segments to merge.
- * @returns {CodePathSegment[]} The merged segments.
+ * Inside of a `finally` block we end up with two parallel paths. If the code path
+ * exits by a control statement (such as `break` or `continue`) from the `finally`
+ * block, then we need to merge the remaining parallel paths back into one.
+ * @param {ForkContext} context The fork context to work on.
+ * @param {Array<CodePathSegment>} segments Segments to merge.
+ * @returns {Array<CodePathSegment>} The merged segments.
  */
 function mergeExtraSegments(context, segments) {
     let currentSegments = segments;
 
+    /*
+     * We need to ensure that the array returned from this function contains no more
+     * than the number of segments that the context allows. `context.count` indicates
+     * how many items should be in the returned array to ensure that the new segment
+     * entries will line up with the already existing segment entries.
+     */
     while (currentSegments.length > context.count) {
         const merged = [];
 
-        for (let i = 0, length = currentSegments.length / 2 | 0; i < length; ++i) {
+        /*
+         * Because `context.count` is a factor of 2 inside of a `finally` block,
+         * we can divide the segment count by 2 to merge the paths together.
+         * This loops through each segment in the list and creates a new `CodePathSegment`
+         * that has the segment and the segment two slots away as previous segments.
+         *
+         * If `currentSegments` is [a,b,c,d], this will create new segments e and f, such
+         * that:
+         *
+         * When `i` is 0:
+         * a->e
+         * c->e
+         *
+         * When `i` is 1:
+         * b->f
+         * d->f
+         */
+        for (let i = 0, length = Math.floor(currentSegments.length / 2); i < length; ++i) {
             merged.push(CodePathSegment.newNext(
                 context.idGenerator.next(),
                 [currentSegments[i], currentSegments[i + length]]
             ));
         }
+
+        /*
+         * Go through the loop condition one more time to see if we have the
+         * number of segments for the context. If not, we'll keep merging paths
+         * of the merged segments until we get there.
+         */
         currentSegments = merged;
     }
+
     return currentSegments;
 }
 
@@ -93,25 +154,55 @@ function mergeExtraSegments(context, segments) {
 //------------------------------------------------------------------------------
 
 /**
- * A class to manage forking.
+ * Manages the forking of code paths.
  */
 class ForkContext {
 
     /**
+     * Creates a new instance.
      * @param {IdGenerator} idGenerator An identifier generator for segments.
-     * @param {ForkContext|null} upper An upper fork context.
-     * @param {number} count A number of parallel segments.
+     * @param {ForkContext|null} upper The preceding fork context.
+     * @param {number} count The number of parallel segments in each element
+     *      of `segmentsList`.
      */
     constructor(idGenerator, upper, count) {
+
+        /**
+         * The ID generator that will generate segment IDs for any new
+         * segments that are created.
+         * @type {IdGenerator}
+         */
         this.idGenerator = idGenerator;
+
+        /**
+         * The preceding fork context.
+         * @type {ForkContext|null}
+         */
         this.upper = upper;
+
+        /**
+         * The number of elements in each element of `segmentsList`. In most
+         * cases, this is 1 but can be 2 when there is a `finally` present,
+         * which forks the code path outside of normal flow. In the case of nested
+         * `finally` blocks, this can be a multiple of 2.
+         * @type {number}
+         */
         this.count = count;
+
+        /**
+         * The segments within this context. Each element in this array has
+         * `count` elements that represent one step in each fork. For example,
+         * when `segmentsList` is `[[a, b], [c, d], [e, f]]`, there is one path
+         * a->c->e and one path b->d->f, and `count` is 2 because each element
+         * is an array with two elements.
+         * @type {Array<Array<CodePathSegment>>}
+         */
         this.segmentsList = [];
     }
 
     /**
-     * The head segments.
-     * @type {CodePathSegment[]}
+     * The segments that begin this fork context.
+     * @type {Array<CodePathSegment>}
      */
     get head() {
         const list = this.segmentsList;
@@ -120,7 +211,7 @@ class ForkContext {
     }
 
     /**
-     * A flag which shows empty.
+     * Indicates if the context contains no segments.
      * @type {boolean}
      */
     get empty() {
@@ -128,7 +219,7 @@ class ForkContext {
     }
 
     /**
-     * A flag which shows reachable.
+     * Indicates if there are any segments that are reachable.
      * @type {boolean}
      */
     get reachable() {
@@ -138,75 +229,82 @@ class ForkContext {
     }
 
     /**
-     * Creates new segments from this context.
-     * @param {number} begin The first index of previous segments.
-     * @param {number} end The last index of previous segments.
-     * @returns {CodePathSegment[]} New segments.
+     * Creates new segments in this context and appends them to the end of the
+     * already existing `CodePathSegment`s specified by `startIndex` and
+     * `endIndex`.
+     * @param {number} startIndex The index of the first segment in the context
+     *      that should be specified as previous segments for the newly created segments.
+     * @param {number} endIndex The index of the last segment in the context
+     *      that should be specified as previous segments for the newly created segments.
+     * @returns {Array<CodePathSegment>} An array of the newly created segments.
      */
-    makeNext(begin, end) {
-        return makeSegments(this, begin, end, CodePathSegment.newNext);
+    makeNext(startIndex, endIndex) {
+        return createSegments(this, startIndex, endIndex, CodePathSegment.newNext);
     }
 
     /**
-     * Creates new segments from this context.
-     * The new segments is always unreachable.
-     * @param {number} begin The first index of previous segments.
-     * @param {number} end The last index of previous segments.
-     * @returns {CodePathSegment[]} New segments.
+     * Creates new unreachable segments in this context and appends them to the end of the
+     * already existing `CodePathSegment`s specified by `startIndex` and
+     * `endIndex`.
+     * @param {number} startIndex The index of the first segment in the context
+     *      that should be specified as previous segments for the newly created segments.
+     * @param {number} endIndex The index of the last segment in the context
+     *      that should be specified as previous segments for the newly created segments.
+     * @returns {Array<CodePathSegment>} An array of the newly created segments.
      */
-    makeUnreachable(begin, end) {
-        return makeSegments(this, begin, end, CodePathSegment.newUnreachable);
+    makeUnreachable(startIndex, endIndex) {
+        return createSegments(this, startIndex, endIndex, CodePathSegment.newUnreachable);
     }
 
     /**
-     * Creates new segments from this context.
-     * The new segments don't have connections for previous segments.
-     * But these inherit the reachable flag from this context.
-     * @param {number} begin The first index of previous segments.
-     * @param {number} end The last index of previous segments.
-     * @returns {CodePathSegment[]} New segments.
+     * Creates new segments in this context and does not append them to the end
+     *  of the already existing `CodePathSegment`s specified by `startIndex` and
+     * `endIndex`. The `startIndex` and `endIndex` are only used to determine if
+     * the new segments should be reachable. If any of the segments in this range
+     * are reachable then the new segments are also reachable; otherwise, the new
+     * segments are unreachable.
+     * @param {number} startIndex The index of the first segment in the context
+     *      that should be considered for reachability.
+     * @param {number} endIndex The index of the last segment in the context
+     *      that should be considered for reachability.
+     * @returns {Array<CodePathSegment>} An array of the newly created segments.
      */
-    makeDisconnected(begin, end) {
-        return makeSegments(this, begin, end, CodePathSegment.newDisconnected);
+    makeDisconnected(startIndex, endIndex) {
+        return createSegments(this, startIndex, endIndex, CodePathSegment.newDisconnected);
     }
 
     /**
-     * Adds segments into this context.
-     * The added segments become the head.
-     * @param {CodePathSegment[]} segments Segments to add.
+     * Adds segments to the head of this context.
+     * @param {Array<CodePathSegment>} segments The segments to add.
      * @returns {void}
      */
     add(segments) {
         assert(segments.length >= this.count, `${segments.length} >= ${this.count}`);
-
         this.segmentsList.push(mergeExtraSegments(this, segments));
     }
 
     /**
-     * Replaces the head segments with given segments.
+     * Replaces the head segments with the given segments.
      * The current head segments are removed.
-     * @param {CodePathSegment[]} segments Segments to add.
+     * @param {Array<CodePathSegment>} replacementHeadSegments The new head segments.
      * @returns {void}
      */
-    replaceHead(segments) {
-        assert(segments.length >= this.count, `${segments.length} >= ${this.count}`);
-
-        this.segmentsList.splice(-1, 1, mergeExtraSegments(this, segments));
+    replaceHead(replacementHeadSegments) {
+        assert(
+            replacementHeadSegments.length >= this.count,
+            `${replacementHeadSegments.length} >= ${this.count}`
+        );
+        this.segmentsList.splice(-1, 1, mergeExtraSegments(this, replacementHeadSegments));
     }
 
     /**
      * Adds all segments of a given fork context into this context.
-     * @param {ForkContext} context A fork context to add.
+     * @param {ForkContext} otherForkContext The fork context to add from.
      * @returns {void}
      */
-    addAll(context) {
-        assert(context.count === this.count);
-
-        const source = context.segmentsList;
-
-        for (let i = 0; i < source.length; ++i) {
-            this.segmentsList.push(source[i]);
-        }
+    addAll(otherForkContext) {
+        assert(otherForkContext.count === this.count);
+        this.segmentsList.push(...otherForkContext.segmentsList);
     }
 
     /**
@@ -218,7 +316,8 @@ class ForkContext {
     }
 
     /**
-     * Creates the root fork context.
+     * Creates a new root context, meaning that there are no parent
+     * fork contexts.
      * @param {IdGenerator} idGenerator An identifier generator for segments.
      * @returns {ForkContext} New fork context.
      */
@@ -233,14 +332,16 @@ class ForkContext {
     /**
      * Creates an empty fork context preceded by a given context.
      * @param {ForkContext} parentContext The parent fork context.
-     * @param {boolean} forkLeavingPath A flag which shows inside of `finally` block.
+     * @param {boolean} shouldForkLeavingPath Indicates that we are inside of
+     *      a `finally` block and should therefore fork the path that leaves
+     *      `finally`.
      * @returns {ForkContext} New fork context.
      */
-    static newEmpty(parentContext, forkLeavingPath) {
+    static newEmpty(parentContext, shouldForkLeavingPath) {
         return new ForkContext(
             parentContext.idGenerator,
             parentContext,
-            (forkLeavingPath ? 2 : 1) * parentContext.count
+            (shouldForkLeavingPath ? 2 : 1) * parentContext.count
         );
     }
 }