feat(linter/plugins): comment-related APIs

Author: lilnasy

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

@@ -169,29 +169,66 @@ export const SOURCE_CODE = Object.freeze({
    * @param nodeOrToken - The AST node or token to check for adjacent comment tokens.
    * @returns Array of `Comment`s in occurrence order.
    */
-  // oxlint-disable-next-line no-unused-vars
   getCommentsBefore(nodeOrToken: NodeOrToken): Comment[] {
-    throw new Error('`sourceCode.getCommentsBefore` not implemented yet'); // TODO
+    if (ast === null) initAst();
+    const { comments } = ast;
+    if (comments.length === 0) return [];
+    const targetStart = nodeOrToken.range[0];
+    let i = comments.length - 1;
+    // linear backwards search for the index of the last comment before the provided node or token, TODO(perf): binary
+    while (i >= 0 && comments[i].range[1] > targetStart) {
+      i--;
+    }
+    return comments.slice(0, i + 1);
   },
 
   /**
    * Get all comment tokens directly after the given node or token.
    * @param nodeOrToken - The AST node or token to check for adjacent comment tokens.
    * @returns Array of `Comment`s in occurrence order.
    */
-  // oxlint-disable-next-line no-unused-vars
   getCommentsAfter(nodeOrToken: NodeOrToken): Comment[] {
-    throw new Error('`sourceCode.getCommentsAfter` not implemented yet'); // TODO
+    if (ast === null) initAst();
+    const { comments } = ast;
+    if (comments.length === 0) return [];
+    const targetEnd = nodeOrToken.range[1];
+    let i = 0;
+    // linear forwards search for the index of the first comment after the provided node or token, TODO(perf): binary
+    while (i < comments.length && comments[i].range[0] < targetEnd) {
+      i++;
+    }
+    return comments.slice(i);
   },
 
   /**
    * Get all comment tokens inside the given node.
    * @param node - The AST node to get the comments for.
    * @returns Array of `Comment`s in occurrence order.
    */
-  // oxlint-disable-next-line no-unused-vars
   getCommentsInside(node: Node): Comment[] {
-    throw new Error('`sourceCode.getCommentsInside` not implemented yet'); // TODO
+    if (ast === null) initAst();
+    const { comments } = ast;
+    if (comments.length === 0) return [];
+    const [rangeStart, rangeEnd] = node.range;
+    let indexStart = null, indexEnd = null;
+    // linear search for the first comment inside the node's range, TODO(perf): binary
+    for (let i = 0; i < comments.length; i++) {
+      const c = comments[i];
+      if (c.range[0] >= rangeStart && c.range[1] <= rangeEnd) {
+        indexStart = i;
+        break;
+      }
+    }
+    if (indexStart === null) return [];
+    // linear search for the last comment inside the node's range, TODO(perf): binary
+    for (let i = indexStart; i < comments.length; i++) {
+      const c = comments[i];
+      if (c.range[1] > rangeEnd) {
+        indexEnd = i;
+        break;
+      }
+    }
+    return comments.slice(indexStart, indexEnd ?? comments.length);
   },
 
   /**
@@ -468,9 +505,16 @@ export const SOURCE_CODE = Object.freeze({
    * @param nodeOrToken2 - The node to check.
    * @returns `true` if one or more comments exist.
    */
-  // oxlint-disable-next-line no-unused-vars
   commentsExistBetween(nodeOrToken1: NodeOrToken, nodeOrToken2: NodeOrToken): boolean {
-    throw new Error('`sourceCode.commentsExistBetween` not implemented yet'); // TODO
+    // find the first comment after nodeOrToken1 end, check if it ends before nodeOrToken2 starts
+    const nodeOrToken1End = nodeOrToken1.range[1];
+    for (let i = 0; i < ast.comments.length; i++) {
+      const c = ast.comments[i];
+      if (c.range[0] >= nodeOrToken1End) {
+        return c.range[1] <= nodeOrToken2.range[0];
+      }
+    }
+    return false;
   },
 
   getAncestors,

apps/oxlint/test/e2e.test.ts

@@ -217,7 +217,7 @@ describe('oxlint CLI', () => {
     }
   });
 
-  it('SourceCode.getAllComments() should return all comments', async () => {
-    await testFixture('getAllComments');
+  it('should support comments-related APIs in `context.sourceCode`', async () => {
+    await testFixture('comments');
   });
 });

apps/oxlint/test/fixtures/comments/.oxlintrc.json

@@ -0,0 +1,6 @@
+{
+  "jsPlugins": ["./plugin.ts"],
+  "rules": {
+    "test-comments/test-comments": "error"
+  }
+}

apps/oxlint/test/fixtures/getAllComments/files/test.js renamed to apps/oxlint/test/fixtures/comments/files/test.js

@@ -0,0 +1,78 @@
+# Exit code
+1
+
+# stdout
+```
+  x test-comments(test-comments): getCommentsAfter(x) returned 5 comments:
+  |   [0] Block: " Block comment 1 " at [31, 52]
+  |   [1] Block: "*\n * JSDoc comment\n " at [54, 78]
+  |   [2] Line: " Line comment 2" at [105, 122]
+  |   [3] Line: " Line comment 3" at [135, 152]
+  |   [4] Block: " Block comment 2 " at [156, 177]
+   ,-[files/test.js:2:1]
+ 1 | // Line comment 1
+ 2 | const x = 1; /* Block comment 1 */
+   : ^^^^^^^^^^^^
+ 3 | 
+   `----
+
+  x test-comments(test-comments): getCommentsBefore(x) returned 1 comments:
+  |   [0] Line: " Line comment 1" at [0, 17]
+   ,-[files/test.js:2:1]
+ 1 | // Line comment 1
+ 2 | const x = 1; /* Block comment 1 */
+   : ^^^^^^^^^^^^
+ 3 | 
+   `----
+
+  x test-comments(test-comments): commentsExistBetween(x, foo): true
+   ,-[files/test.js:2:1]
+ 1 | // Line comment 1
+ 2 | const x = 1; /* Block comment 1 */
+   : ^^^^^^^^^^^^
+ 3 | 
+   `----
+
+  x test-comments(test-comments): getAllComments() returned 6 comments:
+  |   [0] Line: " Line comment 1" at [0, 17]
+  |   [1] Block: " Block comment 1 " at [31, 52]
+  |   [2] Block: "*\n * JSDoc comment\n " at [54, 78]
+  |   [3] Line: " Line comment 2" at [105, 122]
+  |   [4] Line: " Line comment 3" at [135, 152]
+  |   [5] Block: " Block comment 2 " at [156, 177]
+    ,-[files/test.js:2:1]
+  1 |     // Line comment 1
+  2 | ,-> const x = 1; /* Block comment 1 */
+  3 | |   
+  4 | |   /**
+  5 | |    * JSDoc comment
+  6 | |    */
+  7 | |   export function foo() {
+  8 | |     // Line comment 2
+  9 | |     return x; // Line comment 3
+ 10 | |   }
+ 11 | |   
+ 12 | `-> /* Block comment 2 */
+    `----
+
+  x test-comments(test-comments): getCommentsInside(foo) returned 2 comments:
+  |   [0] Line: " Line comment 2" at [105, 122]
+  |   [1] Line: " Line comment 3" at [135, 152]
+    ,-[files/test.js:7:1]
+  6 |      */
+  7 | ,-> export function foo() {
+  8 | |     // Line comment 2
+  9 | |     return x; // Line comment 3
+ 10 | `-> }
+ 11 |     
+    `----
+
+Found 0 warnings and 5 errors.
+Finished in Xms on 1 file using X threads.
+```
+
+# stderr
+```
+WARNING: JS plugins are experimental and not subject to semver.
+Breaking changes are possible while JS plugins support is under development.
+```

apps/oxlint/test/fixtures/comments/output.snap.md

@@ -0,0 +1,64 @@
+import { definePlugin } from '../../../dist/index.js';
+import type { Rule } from '../../../dist/index.js';
+
+const testCommentsRule: Rule = {
+  create(context) {
+    const { sourceCode } = context;
+    const { ast } = sourceCode;
+    const { body } = ast;
+
+    const comments = sourceCode.getAllComments();
+    context.report({
+      message: `getAllComments() returned ${comments.length} comments:\n` +
+        comments.map((c, i) => `  [${i}] ${c.type}: ${JSON.stringify(c.value)} at [${c.range[0]}, ${c.range[1]}]`).join(
+          '\n',
+        ),
+      node: context.sourceCode.ast,
+    });
+
+    const constX = body.find((n) => n.type === 'VariableDeclaration');
+    const before = sourceCode.getCommentsBefore(constX);
+    const after = sourceCode.getCommentsAfter(constX);
+    context.report({
+      message: `getCommentsBefore(x) returned ${before.length} comments:\n` +
+        before.map((c, i) => `  [${i}] ${c.type}: ${JSON.stringify(c.value)} at [${c.range[0]}, ${c.range[1]}]`).join(
+          '\n',
+        ),
+      node: constX,
+    });
+    context.report({
+      message: `getCommentsAfter(x) returned ${after.length} comments:\n` +
+        after.map((c, i) => `  [${i}] ${c.type}: ${JSON.stringify(c.value)} at [${c.range[0]}, ${c.range[1]}]`).join(
+          '\n',
+        ),
+      node: constX,
+    });
+
+    const functionFoo = body.find((n) => n.type === 'ExportNamedDeclaration');
+    const insideFn = sourceCode.getCommentsInside(functionFoo);
+    context.report({
+      message: `getCommentsInside(foo) returned ${insideFn.length} comments:\n` +
+        insideFn.map((c, i) => `  [${i}] ${c.type}: ${JSON.stringify(c.value)} at [${c.range[0]}, ${c.range[1]}]`).join(
+          '\n',
+        ),
+      node: functionFoo,
+    });
+
+    const commentsBetween = sourceCode.commentsExistBetween(constX, functionFoo);
+    context.report({
+      message: `commentsExistBetween(x, foo): ${commentsBetween}`,
+      node: constX,
+    });
+
+    return {};
+  },
+};
+
+export default definePlugin({
+  meta: {
+    name: 'test-comments',
+  },
+  rules: {
+    'test-comments': testCommentsRule,
+  },
+});