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

Author: lilnasy

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

@@ -324,7 +324,91 @@ export function getTokenBefore(
   nodeOrToken: NodeOrToken | Comment,
   skipOptions?: SkipOptions | number | FilterFn | null,
 ): Token | null {
-  throw new Error('`sourceCode.getTokenBefore` not implemented yet'); // TODO
+  if (tokens === null) initTokens();
+  assertIsNonNull(tokens);
+  assertIsNonNull(comments);
+
+  // Number of tokens preceding the given node to skip
+  let skip =
+    typeof skipOptions === 'number'
+      ? skipOptions
+      : typeof skipOptions === 'object' && skipOptions !== null
+        ? skipOptions.skip
+        : null;
+
+  const filter =
+    typeof skipOptions === 'function'
+      ? skipOptions
+      : typeof skipOptions === 'object' && skipOptions !== null
+        ? skipOptions.filter
+        : null;
+
+  // Whether to return comment tokens
+  const includeComments =
+    typeof skipOptions === 'object' &&
+    skipOptions !== null &&
+    'includeComments' in skipOptions &&
+    skipOptions.includeComments;
+
+  // Source array of tokens to search in
+  let nodeTokens: Token[] | null = null;
+  if (includeComments) {
+    if (tokensWithComments === null) {
+      // TODO: `tokens` and `comments` are already sorted, so there's a more efficient algorithm to merge them.
+      // That'd certainly be faster in Rust, but maybe here it's faster to leave it to JS engine to sort them?
+      // TODO: Once we have our own tokens which have `start` and `end` properties, we can use them instead of `range`.
+      tokensWithComments = [...tokens, ...comments].sort((a, b) => a.range[0] - b.range[0]);
+    }
+    nodeTokens = tokensWithComments;
+  } else {
+    nodeTokens = tokens;
+  }
+
+  const nodeStart = nodeOrToken.range[0];
+
+  // Index of the token immediately before the given node, token, or comment.
+  let beforeIndex = 0;
+  let hi = nodeTokens.length;
+
+  while (beforeIndex < hi) {
+    const mid = (beforeIndex + hi) >> 1;
+    if (nodeTokens[mid].range[0] < nodeStart) {
+      beforeIndex = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+
+  beforeIndex -= 1;
+
+  if (typeof filter !== 'function') {
+    if (typeof skip !== 'number') {
+      return nodeTokens[beforeIndex] ?? null;
+    } else {
+      return nodeTokens[beforeIndex - skip] ?? null;
+    }
+  } else {
+    if (typeof skip !== 'number') {
+      while (beforeIndex >= 0) {
+        const token = nodeTokens[beforeIndex];
+        if (filter(token)) {
+          return token;
+        }
+        beforeIndex -= 1;
+      }
+    } else {
+      while (beforeIndex >= 0) {
+        const token = nodeTokens[beforeIndex];
+        if (filter(token)) {
+          if (skip === 0) return token;
+          skip -= 1;
+        }
+        beforeIndex -= 1;
+      }
+    }
+  }
+
+  return null;
 }
 /* oxlint-enable no-unused-vars */
 

apps/oxlint/test/tokens.test.ts

@@ -1,30 +1,31 @@
 import assert from 'node:assert';
 import { describe, it, vi } from 'vitest';
-import { getTokens } from '../src-js/plugins/tokens.js';
+import { getTokens, getTokenBefore } from '../src-js/plugins/tokens.js';
+import { resetSourceAndAst } from '../src-js/plugins/source_code.js';
 import type { Node } from '../src-js/plugins/types.js';
 
-let sourceText = 'null;';
+let sourceText = '/*A*/var answer/*B*/=/*C*/a/*D*/* b/*E*///F\n    call();\n/*Z*/';
 
-vi.mock('../src-js/plugins/source_code.ts', () => {
+vi.mock('../src-js/plugins/source_code.ts', async (importOriginal) => {
+  const original: any = await importOriginal();
   return {
+    ...original,
     get sourceText() {
       return sourceText;
     },
   };
 });
 
+// TODO: We are lying about `Program`'s range here.
+// The range provided by `@typescript-eslint/typescript-estree` does not match the assertions for that of `espree`.
+// The deviation is being corrected in upcoming releases of ESLint and TS-ESLint.
+// https://eslint.org/blog/2025/10/whats-coming-in-eslint-10.0.0/#updates-to-program-ast-node-range-coverage
+// https://github.com/typescript-eslint/typescript-eslint/issues/11026#issuecomment-3421887632
+const Program = { range: [5, 55] } as Node;
+const BinaryExpression = { range: [26, 35] } as Node;
+
 // https://github.com/eslint/eslint/blob/v9.39.1/tests/lib/languages/js/source-code/token-store.js#L62
 describe('when calling getTokens', () => {
-  sourceText = '/*A*/var answer/*B*/=/*C*/a/*D*/* b/*E*///F\n    call();\n/*Z*/';
-
-  // TODO: We are lying about `Program`'s range here.
-  // The range provided by `@typescript-eslint/typescript-estree` does not match the assertions for that of `espree`.
-  // The deviation is being corrected in upcoming releases of ESLint and TS-ESLint.
-  // https://eslint.org/blog/2025/10/whats-coming-in-eslint-10.0.0/#updates-to-program-ast-node-range-coverage
-  // https://github.com/typescript-eslint/typescript-eslint/issues/11026#issuecomment-3421887632
-  const Program = { range: [5, 55] } as Node;
-  const BinaryExpression = { range: [26, 35] } as Node;
-
   it('should retrieve all tokens for root node', () => {
     assert.deepStrictEqual(
       getTokens(Program).map((token) => token.value),
@@ -104,3 +105,93 @@ describe('when calling getTokens', () => {
     );
   });
 });
+
+describe('when calling getTokenBefore', () => {
+  it('should retrieve one token before a node', () => {
+    assert.strictEqual(getTokenBefore(BinaryExpression)!.value, '=');
+  });
+
+  it('should skip a given number of tokens', () => {
+    assert.strictEqual(getTokenBefore(BinaryExpression, 1)!.value, 'answer');
+    assert.strictEqual(getTokenBefore(BinaryExpression, 2)!.value, 'var');
+  });
+
+  it('should skip a given number of tokens with skip option', () => {
+    assert.strictEqual(getTokenBefore(BinaryExpression, { skip: 1 })!.value, 'answer');
+    assert.strictEqual(getTokenBefore(BinaryExpression, { skip: 2 })!.value, 'var');
+  });
+
+  it('should retrieve matched token with filter option', () => {
+    assert.strictEqual(getTokenBefore(BinaryExpression, (t) => t.value !== '=')!.value, 'answer');
+  });
+
+  it('should retrieve matched token with skip and filter options', () => {
+    assert.strictEqual(
+      getTokenBefore(BinaryExpression, {
+        skip: 1,
+        filter: (t) => t.value !== '=',
+      })!.value,
+      'var',
+    );
+  });
+
+  it('should retrieve one token or comment before a node with includeComments option', () => {
+    assert.strictEqual(
+      getTokenBefore(BinaryExpression, {
+        includeComments: true,
+      })!.value,
+      'C',
+    );
+  });
+
+  it('should retrieve one token or comment before a node with includeComments and skip options', () => {
+    assert.strictEqual(
+      getTokenBefore(BinaryExpression, {
+        includeComments: true,
+        skip: 1,
+      })!.value,
+      '=',
+    );
+  });
+
+  it('should retrieve one token or comment before a node with includeComments and skip and filter options', () => {
+    assert.strictEqual(
+      getTokenBefore(BinaryExpression, {
+        includeComments: true,
+        skip: 1,
+        filter: (t) => t.type.startsWith('Block'),
+      })!.value,
+      'B',
+    );
+  });
+
+  it('should retrieve the previous node if the comment at the end of source code is specified.', () => {
+    resetSourceAndAst();
+    sourceText = 'a + b /*comment*/';
+    // TODO: this verbatim range should be replaced with `ast.comments[0]`
+    const token = getTokenBefore({ range: [6, 14] } as Node);
+
+    assert.strictEqual(token!.value, 'b');
+    resetSourceAndAst();
+  });
+
+  it('should retrieve the previous comment if the first token is specified.', () => {
+    resetSourceAndAst();
+    sourceText = '/*comment*/ a + b';
+    // TODO: this verbatim range should be replaced with `ast.tokens[0]`
+    const token = getTokenBefore({ range: [12, 13] } as Node, { includeComments: true });
+
+    assert.strictEqual(token!.value, 'comment');
+    resetSourceAndAst();
+  });
+
+  it('should retrieve null if the first comment is specified.', () => {
+    resetSourceAndAst();
+    sourceText = '/*comment*/ a + b';
+    // TODO: this verbatim range should be replaced with `ast.comments[0]`
+    const token = getTokenBefore({ range: [0, 11] } as Node, { includeComments: true });
+
+    assert.strictEqual(token, null);
+    resetSourceAndAst();
+  });
+});