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

Author: lilnasy

apps/oxlint/test/tokens.test.ts

@@ -1,9 +1,9 @@
 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 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', () => {
   return {
@@ -13,18 +13,16 @@ vi.mock('../src-js/plugins/source_code.ts', () => {
   };
 });
 
+// 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 +102,87 @@ 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.', () => {
+    sourceText = 'a + b /*comment*/';
+    // TODO: the manual range should be replaced with `ast.comments[0]`
+    const token = getTokenBefore({ range: [6, 14] } as Node);
+
+    assert.strictEqual(token!.value, 'b');
+  });
+
+  it('should retrieve the previous comment if the first token is specified.', () => {
+    sourceText = '/*comment*/ a + b';
+    // TODO: the manual range should be replaced with `ast.tokens[0]`
+    const token = getTokenBefore({ range: [0, 11] } as Node, { includeComments: true });
+
+    assert.strictEqual(token!.value, 'comment');
+  });
+
+  it('should retrieve null if the first comment is specified.', () => {
+    sourceText = '/*comment*/ a + b';
+    // TODO: the manual range should be replaced with `ast.comments[0]`
+    const token = getTokenBefore({ range: [12, 13] } as Node, { includeComments: true });
+
+    assert.strictEqual(token, null);
+  });
+});