Update: Add includeComments to getTokenByRangeStart (fixes #8068) (#8069

)

* Update: Add includeComments to getTokenByRangeStart (fixes #8068)

* Remove @Private from public methods

docs/developer-guide/working-with-rules.md

@@ -280,18 +280,21 @@ Once you have an instance of `SourceCode`, you can use the methods on it to work
 * `getLastTokensBetween(nodeOrToken1, nodeOrToken2, countOptions)` - returns the last `count` tokens between two nodes or tokens.
 * `getTokens(node)` - returns all tokens for the given node.
 * `getTokensBetween(nodeOrToken1, nodeOrToken2)` - returns all tokens between two nodes.
-* `getTokenByRangeStart(index)` - returns the token whose range starts at the given index in the source.
+* `getTokenByRangeStart(index, rangeOptions)` - returns the token whose range starts at the given index in the source.
 * `getNodeByRangeIndex(index)` - returns the deepest node in the AST containing the given source index.
 
 > `skipOptions` is an object which has 3 properties; `skip`, `includeComments`, and `filter`. Default is `{skip: 0, includeComments: false, filter: null}`.
-> - The `skip` is a positive integer, the number of skipping tokens. If `filter` option is given at the same time, it doesn't count filtered tokens as skipped.
-> - The `includeComments` is a boolean value, the flag to include comment tokens into the result.
-> - The `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token.
+> - `skip` is a positive integer, the number of skipping tokens. If `filter` option is given at the same time, it doesn't count filtered tokens as skipped.
+> - `includeComments` is a boolean value, the flag to include comment tokens into the result.
+> - `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token.
 >
 > `countOptions` is an object which has 3 properties; `count`, `includeComments`, and `filter`. Default is `{count: 0, includeComments: false, filter: null}`.
-> - The `count` is a positive integer, the maximum number of returning tokens.
-> - The `includeComments` is a boolean value, the flag to include comment tokens into the result.
-> - The `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token.
+> - `count` is a positive integer, the maximum number of returning tokens.
+> - `includeComments` is a boolean value, the flag to include comment tokens into the result.
+> - `filter` is a function which gets a token as the first argument, if the function returns `false` then the result excludes the token.
+>
+> `rangeOptions` is an object which has 1 property: `includeComments`.
+> - `includeComments` is a boolean value, the flag to include comment tokens into the result.
 
 There are also some properties you can access:
 

lib/token-store/backward-token-comment-cursor.js

@@ -17,7 +17,6 @@ const utils = require("./utils");
 
 /**
  * The cursor which iterates tokens and comments in reverse.
- * @private
  */
 module.exports = class BackwardTokenCommentCursor extends Cursor {
 

lib/token-store/backward-token-cursor.js

@@ -17,7 +17,6 @@ const utils = require("./utils");
 
 /**
  * The cursor which iterates tokens only in reverse.
- * @private
  */
 module.exports = class BackwardTokenCursor extends Cursor {
 

lib/token-store/cursor.js

@@ -30,7 +30,6 @@
  *     - SkipCursor .............. The cursor which ignores the first few tokens.
  *     - LimitCursor ............. The cursor which limits the count of tokens.
  *
- * @private
  */
 module.exports = class Cursor {
 

lib/token-store/cursors.js

@@ -37,7 +37,24 @@ class CursorFactory {
     }
 
     /**
-     * Creates the cursor iterates tokens with normalized options.
+     * Creates a base cursor instance that can be decorated by createCursor.
+     *
+     * @param {Token[]} tokens - The array of tokens.
+     * @param {Comment[]} comments - The array of comments.
+     * @param {Object} indexMap - The map from locations to indices in `tokens`.
+     * @param {number} startLoc - The start location of the iteration range.
+     * @param {number} endLoc - The end location of the iteration range.
+     * @param {boolean} includeComments - The flag to iterate comments as well.
+     * @returns {Cursor} The created base cursor.
+     */
+    createBaseCursor(tokens, comments, indexMap, startLoc, endLoc, includeComments) {
+        const Cursor = includeComments ? this.TokenCommentCursor : this.TokenCursor;
+
+        return new Cursor(tokens, comments, indexMap, startLoc, endLoc);
+    }
+
+    /**
+     * Creates a cursor that iterates tokens with normalized options.
      *
      * @param {Token[]} tokens - The array of tokens.
      * @param {Comment[]} comments - The array of comments.
@@ -49,11 +66,9 @@ class CursorFactory {
      * @param {number} skip - The count of tokens the cursor skips.
      * @param {number} count - The maximum count of tokens the cursor iterates. Zero is no iteration for backward compatibility.
      * @returns {Cursor} The created cursor.
-     * @private
      */
     createCursor(tokens, comments, indexMap, startLoc, endLoc, includeComments, filter, skip, count) {
-        const Cursor = includeComments ? this.TokenCommentCursor : this.TokenCursor;
-        let cursor = new Cursor(tokens, comments, indexMap, startLoc, endLoc);
+        let cursor = this.createBaseCursor(tokens, comments, indexMap, startLoc, endLoc, includeComments);
 
         if (filter) {
             cursor = new FilterCursor(cursor, filter);

lib/token-store/decorative-cursor.js

@@ -16,7 +16,6 @@ const Cursor = require("./cursor");
 
 /**
  * The abstract class about cursors which manipulate another cursor.
- * @private
  */
 module.exports = class DecorativeCursor extends Cursor {
 

lib/token-store/filter-cursor.js

@@ -16,7 +16,6 @@ const DecorativeCursor = require("./decorative-cursor");
 
 /**
  * The decorative cursor which ignores specified tokens.
- * @private
  */
 module.exports = class FilterCursor extends DecorativeCursor {
 

lib/token-store/forward-token-comment-cursor.js

@@ -17,7 +17,6 @@ const utils = require("./utils");
 
 /**
  * The cursor which iterates tokens and comments.
- * @private
  */
 module.exports = class ForwardTokenCommentCursor extends Cursor {
 

lib/token-store/forward-token-cursor.js

@@ -17,7 +17,6 @@ const utils = require("./utils");
 
 /**
  * The cursor which iterates tokens only.
- * @private
  */
 module.exports = class ForwardTokenCursor extends Cursor {
 

lib/token-store/index.js

@@ -236,10 +236,20 @@ module.exports = class TokenStore {
     /**
      * Gets the token starting at the specified index.
      * @param {number} offset - Index of the start of the token's range.
+     * @param {Object} [options=0] - The option object.
+     * @param {boolean} [options.includeComments=false] - The flag to iterate comments as well.
      * @returns {Token|null} The token starting at index, or null if no such token.
      */
-    getTokenByRangeStart(offset) {
-        const token = this.tokens[this.indexMap[offset]] || null;
+    getTokenByRangeStart(offset, options) {
+        const includeComments = options && options.includeComments;
+        const token = cursors.forward.createBaseCursor(
+            this.tokens,
+            this.comments,
+            this.indexMap,
+            offset,
+            -1,
+            includeComments
+        ).getOneToken();
 
         if (token && token.range[0] === offset) {
             return token;

lib/token-store/limit-cursor.js

@@ -16,7 +16,6 @@ const DecorativeCursor = require("./decorative-cursor");
 
 /**
  * The decorative cursor which limits the number of tokens.
- * @private
  */
 module.exports = class LimitCursor extends DecorativeCursor {
 

lib/token-store/padded-token-cursor.js

@@ -17,7 +17,6 @@ const ForwardTokenCursor = require("./forward-token-cursor");
 /**
  * The cursor which iterates tokens only, with inflated range.
  * This is for the backward compatibility of padding options.
- * @private
  */
 module.exports = class PaddedTokenCursor extends ForwardTokenCursor {
 

lib/token-store/skip-cursor.js

@@ -16,7 +16,6 @@ const DecorativeCursor = require("./decorative-cursor");
 
 /**
  * The decorative cursor which ignores the first few tokens.
- * @private
  */
 module.exports = class SkipCursor extends DecorativeCursor {
 

lib/token-store/utils.js

@@ -36,7 +36,6 @@ function getStartLocation(token) {
  * @param {(Token|Comment)[]} tokens - It searches the token in this list.
  * @param {number} location - The location to search.
  * @returns {number} The found index or `tokens.length`.
- * @private
  */
 exports.search = function search(tokens, location) {
     return lodash.sortedIndexBy(
@@ -54,7 +53,6 @@ exports.search = function search(tokens, location) {
  * @param {Object} indexMap - The map from locations to indices.
  * @param {number} startLoc - The location to get an index.
  * @returns {number} The index.
- * @private
  */
 exports.getFirstIndex = function getFirstIndex(tokens, indexMap, startLoc) {
     if (startLoc in indexMap) {
@@ -82,7 +80,6 @@ exports.getFirstIndex = function getFirstIndex(tokens, indexMap, startLoc) {
  * @param {Object} indexMap - The map from locations to indices.
  * @param {number} endLoc - The location to get an index.
  * @returns {number} The index.
- * @private
  */
 exports.getLastIndex = function getLastIndex(tokens, indexMap, endLoc) {
     if (endLoc in indexMap) {

tests/lib/token-store.js

@@ -1132,6 +1132,25 @@ describe("TokenStore", () => {
             assert.isNull(result);
         });
 
+        it("should return a comment token when includeComments is true", () => {
+            const result = store.getTokenByRangeStart(15, { includeComments: true });
+
+            assert.equal(result.type, "Block");
+            assert.equal(result.value, "B");
+        });
+
+        it("should not return a comment token at the supplied index when includeComments is false", () => {
+            const result = store.getTokenByRangeStart(15, { includeComments: false });
+
+            assert.isNull(result);
+        });
+
+        it("should not return comment tokens by default", () => {
+            const result = store.getTokenByRangeStart(15);
+
+            assert.isNull(result);
+        });
+
     });
 
     describe("when calling getTokenOrCommentBefore", () => {