feat(linter/plugins): implement SourceCode#getFirstTokens()

Author: lilnasy

apps/oxlint/src-js/plugins/tokens.ts

@@ -9,7 +9,7 @@ import { debugAssertIsNonNull } from '../utils/asserts.js';
 import type { Comment, Node, NodeOrToken } from './types.ts';
 import type { Span } from './location.ts';
 
-const { max } = Math;
+const { max, min } = Math;
 
 /**
  * Options for various `SourceCode` methods e.g. `getFirstToken`.
@@ -284,11 +284,100 @@ export function getFirstToken(node: Node, skipOptions?: SkipOptions | number | F
  *   If this is a function then it's `options.filter`.
  * @returns Array of `Token`s.
  */
-/* oxlint-disable no-unused-vars */
 export function getFirstTokens(node: Node, countOptions?: CountOptions | number | FilterFn | null): Token[] {
-  throw new Error('`sourceCode.getFirstTokens` not implemented yet'); // TODO
+  if (tokens === null) initTokens();
+  debugAssertIsNonNull(tokens);
+  debugAssertIsNonNull(comments);
+
+  const count =
+    typeof countOptions === 'number'
+      ? countOptions
+      : typeof countOptions === 'object' && countOptions !== null
+        ? countOptions.count
+        : null;
+
+  const filter =
+    typeof countOptions === 'function'
+      ? countOptions
+      : typeof countOptions === 'object' && countOptions !== null
+        ? countOptions.filter
+        : null;
+
+  const includeComments =
+    typeof countOptions === 'object' &&
+    countOptions !== null &&
+    'includeComments' in countOptions &&
+    countOptions.includeComments;
+
+  let nodeTokens: Token[] | null = null;
+  if (includeComments) {
+    if (tokensWithComments === null) {
+      tokensWithComments = [...tokens, ...comments].sort((a, b) => a.range[0] - b.range[0]);
+    }
+    nodeTokens = tokensWithComments;
+  } else {
+    nodeTokens = tokens;
+  }
+
+  const { range } = node,
+    rangeStart = range[0],
+    rangeEnd = range[1];
+
+  // Binary search for first token within `node`'s range
+  const tokensLength = nodeTokens.length;
+  let sliceStart = tokensLength;
+  for (let lo = 0; lo < sliceStart; ) {
+    const mid = (lo + sliceStart) >> 1;
+    if (nodeTokens[mid].range[0] < rangeStart) {
+      lo = mid + 1;
+    } else {
+      sliceStart = mid;
+    }
+  }
+
+  // Binary search for the first token outside `node`'s range
+  let sliceEnd = tokensLength;
+  for (let lo = sliceStart; lo < sliceEnd; ) {
+    const mid = (lo + sliceEnd) >> 1;
+    if (nodeTokens[mid].range[0] < rangeEnd) {
+      lo = mid + 1;
+    } else {
+      sliceEnd = mid;
+    }
+  }
+
+  let firstTokens: Token[];
+  if (typeof filter !== 'function') {
+    if (typeof count !== 'number') {
+      firstTokens = nodeTokens.slice(sliceStart, sliceEnd);
+    } else {
+      firstTokens = nodeTokens.slice(sliceStart, min(sliceStart + count, sliceEnd));
+    }
+  } else {
+    if (typeof count !== 'number') {
+      firstTokens = [];
+      for (let i = sliceStart; i < sliceEnd; i++) {
+        const token = nodeTokens[i];
+        if (filter(token)) {
+          firstTokens.push(token);
+        }
+      }
+    } else {
+      firstTokens = [];
+      for (let i = sliceStart; i < sliceEnd; i++) {
+        const token = nodeTokens[i];
+        if (filter(token)) {
+          firstTokens.push(token);
+          if (firstTokens.length === count) {
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  return firstTokens;
 }
-/* oxlint-enable no-unused-vars */
 
 /**
  * Get the last token of the given node.

apps/oxlint/test/tokens.test.ts

@@ -397,11 +397,95 @@ describe('when calling getTokensAfter', () => {
   });
 });
 
+// https://github.com/eslint/eslint/blob/v9.39.1/tests/lib/languages/js/source-code/token-store.js#L594-L673
 describe('when calling getFirstTokens', () => {
-  /* oxlint-disable-next-line no-disabled-tests expect-expect */
-  it('is to be implemented');
-  /* oxlint-disable-next-line no-unused-expressions */
-  getFirstTokens;
+  it("should retrieve zero tokens from a node's token stream", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, 0).map((token) => token.value),
+      [],
+    );
+  });
+
+  it("should retrieve one token from a node's token stream", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, 1).map((token) => token.value),
+      ['a'],
+    );
+  });
+
+  it("should retrieve more than one token from a node's token stream", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, 2).map((token) => token.value),
+      ['a', '*'],
+    );
+  });
+
+  it("should retrieve all tokens from a node's token stream", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, 9e9).map((token) => token.value),
+      ['a', '*', 'b'],
+    );
+  });
+
+  it("should retrieve more than one token from a node's token stream with count option", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, { count: 2 }).map((token) => token.value),
+      ['a', '*'],
+    );
+  });
+
+  it("should retrieve matched tokens from a node's token stream with filter option", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, (t) => t.type === 'Identifier').map((token) => token.value),
+      ['a', 'b'],
+    );
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, {
+        filter: (t) => t.type === 'Identifier',
+      }).map((token) => token.value),
+      ['a', 'b'],
+    );
+  });
+
+  it("should retrieve matched tokens from a node's token stream with filter and count options", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, {
+        count: 1,
+        filter: (t) => t.type === 'Identifier',
+      }).map((token) => token.value),
+      ['a'],
+    );
+  });
+
+  it("should retrieve all tokens and comments from a node's token stream with includeComments option", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, {
+        includeComments: true,
+      }).map((token) => token.value),
+      ['a', 'D', '*', 'b'],
+    );
+  });
+
+  it("should retrieve several tokens and comments from a node's token stream with includeComments and count options", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, {
+        includeComments: true,
+        count: 3,
+      }).map((token) => token.value),
+      ['a', 'D', '*'],
+    );
+  });
+
+  it("should retrieve several tokens and comments from a node's token stream with includeComments and count and filter options", () => {
+    assert.deepStrictEqual(
+      getFirstTokens(BinaryExpression, {
+        includeComments: true,
+        count: 3,
+        filter: (t) => t.value !== 'a',
+      }).map((token) => token.value),
+      ['D', '*', 'b'],
+    );
+  });
 });
 
 describe('when calling getFirstToken', () => {