feat(linter/plugins): add SourceCode API

Author: overlookmotel

apps/oxlint/src-js/index.ts

@@ -5,6 +5,7 @@ import type { BeforeHook, Visitor, VisitorWithHooks } from './plugins/types.ts';
 export type { Context, Diagnostic } from './plugins/context.ts';
 export type { Fix, Fixer, FixFn, NodeOrToken, Range } from './plugins/fix.ts';
 export type { CreateOnceRule, CreateRule, Plugin, Rule } from './plugins/load.ts';
+export type { SourceCode } from './plugins/source_code.ts';
 export type { AfterHook, BeforeHook, Node, RuleMeta, Visitor, VisitorWithHooks } from './plugins/types.ts';
 
 const { defineProperty, getPrototypeOf, hasOwn, setPrototypeOf, create: ObjectCreate } = Object;

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

@@ -1,4 +1,5 @@
 import { getFixes } from './fix.js';
+import { setupSourceCodeForFile, SourceCode } from './source_code.js';
 
 import type { Fix, FixFn } from './fix.ts';
 import type { Node } from './types.ts';
@@ -32,11 +33,13 @@ export const diagnostics: DiagnosticReport[] = [];
  * @param context - `Context` object
  * @param ruleIndex - Index of this rule within `ruleIds` passed from Rust
  * @param filePath - Absolute path of file being linted
+ * @param sourceText - Source text of file being linted
  */
 export let setupContextForFile: (
   context: Context,
   ruleIndex: number,
   filePath: string,
+  sourceText: string,
 ) => void;
 
 /**
@@ -65,6 +68,10 @@ export interface InternalContext {
   ruleIndex: number;
   // Absolute path of file being linted
   filePath: string;
+  // `SourceCode` class instance for this rule.
+  // Rule has single `SourceCode` instance that is updated for each file
+  // (NOT new `SourceCode` instance for each file).
+  sourceCode: SourceCode;
   // Options
   options: unknown[];
   // `true` if rule can provide fixes (`meta.fixable` in `RuleMeta` is 'code' or 'whitespace')
@@ -89,6 +96,7 @@ export class Context {
     this.#internal = {
       id: fullRuleName,
       filePath: '',
+      sourceCode: new SourceCode(),
       ruleIndex: -1,
       options: [],
       isFixable,
@@ -116,6 +124,11 @@ export class Context {
     return getInternal(this, 'access `context.options`').options;
   }
 
+  // Getter for `SourceCode` for file being linted.
+  get sourceCode() {
+    return getInternal(this, 'access `context.sourceCode`').sourceCode;
+  }
+
   /**
    * Report error.
    * @param diagnostic - Diagnostic object
@@ -135,11 +148,12 @@ export class Context {
   }
 
   static {
-    setupContextForFile = (context, ruleIndex, filePath) => {
+    setupContextForFile = (context, ruleIndex, filePath, sourceText) => {
       // TODO: Support `options`
       const internal = context.#internal;
       internal.ruleIndex = ruleIndex;
       internal.filePath = filePath;
+      setupSourceCodeForFile(internal.sourceCode, sourceText);
     };
 
     getInternal = (context, actionDescription) => {

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

@@ -104,14 +104,21 @@ function lintFileImpl(filePath: string, bufferId: number, buffer: Uint8Array | n
     throw new Error('Expected `ruleIds` to be a non-zero len array');
   }
 
+  // Decode source text from buffer
+  const { uint32 } = buffer,
+    programPos = uint32[DATA_POINTER_POS_32],
+    sourceByteLen = uint32[(programPos + SOURCE_LEN_OFFSET) >> 2];
+
+  const sourceText = textDecoder.decode(buffer.subarray(0, sourceByteLen));
+
   // Get visitors for this file from all rules
   initCompiledVisitor();
 
   for (let i = 0; i < ruleIds.length; i++) {
     const ruleId = ruleIds[i],
       ruleAndContext = registeredRules[ruleId];
     const { rule, context } = ruleAndContext;
-    setupContextForFile(context, i, filePath);
+    setupContextForFile(context, i, filePath, sourceText);
 
     let { visitor } = ruleAndContext;
     if (visitor === null) {
@@ -139,12 +146,6 @@ function lintFileImpl(filePath: string, bufferId: number, buffer: Uint8Array | n
   // Some rules seen in the wild return an empty visitor object from `create` if some initial check fails
   // e.g. file extension is not one the rule acts on.
   if (needsVisit) {
-    const { uint32 } = buffer,
-      programPos = uint32[DATA_POINTER_POS_32],
-      sourceByteLen = uint32[(programPos + SOURCE_LEN_OFFSET) >> 2];
-
-    const sourceText = textDecoder.decode(buffer.subarray(0, sourceByteLen));
-
     // `preserveParens` argument is `false`, to match ESLint.
     // ESLint does not include `ParenthesizedExpression` nodes in its AST.
     const program = deserializeProgramOnly(buffer, sourceText, sourceByteLen, false);

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

@@ -0,0 +1,52 @@
+import type { Node } from './types.ts';
+
+const { max } = Math;
+
+/**
+ * Update a `SourceCode` with file-specific data.
+ *
+ * We have to define this function within class body, as it's not possible to access private property
+ * `#sourceText` from outside the class.
+ * We don't use a normal class method, because we don't want to expose this to user.
+ *
+ * @param code - `SourceCode` object
+ * @param sourceText - Source text for file being linted
+ */
+export let setupSourceCodeForFile: (code: SourceCode, sourceText: string) => void;
+
+/**
+ * `SourceCode` class.
+ *
+ * Each rule has its own `SourceCode` object. It is stored in `Context` for that rule.
+ *
+ * A new `SourceCode` instance is NOT generated for each file.
+ * The `SourceCode` instance for the rule is updated for each file.
+ */
+export class SourceCode {
+  // Source text.
+  // Initially `null`, but set to source string by `setupSourceCodeForFile`.
+  #sourceText: string = null;
+
+  getText(
+    node?: Node | null | undefined,
+    beforeCount?: number | null | undefined,
+    afterCount?: number | null | undefined,
+  ) {
+    // ESLint treats all falsy values for `node` as undefined
+    if (!node) return this.#sourceText;
+
+    // ESLint ignores falsy values for `beforeCount` and `afterCount`
+    let { start, end } = node;
+    if (beforeCount) start = max(start - beforeCount, 0);
+    if (afterCount) end += afterCount;
+    return this.#sourceText.slice(start, end);
+  }
+
+  // TODO: Add more methods
+
+  static {
+    setupSourceCodeForFile = (code, sourceText) => {
+      code.#sourceText = sourceText;
+    };
+  }
+}

apps/oxlint/test/e2e.test.ts

@@ -123,6 +123,10 @@ describe('oxlint CLI', () => {
     await testFixture('context_properties');
   });
 
+  it('should give access to source code via `context.sourceCode`', async () => {
+    await testFixture('sourceCode');
+  });
+
   it('should support `createOnce`', async () => {
     await testFixture('createOnce');
   });

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

@@ -75,6 +75,12 @@
    : ^
    `----
 
+  x create-once-plugin(always-run): createOnce: sourceCode: Cannot access `context.sourceCode` in `createOnce`
+   ,-[files/1.js:1:1]
+ 1 | let x;
+   : ^
+   `----
+
   x create-once-plugin(always-run): createOnce: this === rule: true
    ,-[files/1.js:1:1]
  1 | let x;
@@ -201,6 +207,12 @@
    : ^
    `----
 
+  x create-once-plugin(always-run): createOnce: sourceCode: Cannot access `context.sourceCode` in `createOnce`
+   ,-[files/2.js:1:1]
+ 1 | let y;
+   : ^
+   `----
+
   x create-once-plugin(always-run): createOnce: this === rule: true
    ,-[files/2.js:1:1]
  1 | let y;
@@ -255,7 +267,7 @@
    :     ^
    `----
 
-Found 0 warnings and 42 errors.
+Found 0 warnings and 44 errors.
 Finished in Xms on 2 files using X threads.
 ```
 

apps/oxlint/test/fixtures/createOnce/plugin.ts

@@ -25,6 +25,7 @@ const alwaysRunRule: Rule = {
     const filenameError = tryCatch(() => context.filename);
     const physicalFilenameError = tryCatch(() => context.physicalFilename);
     const optionsError = tryCatch(() => context.options);
+    const sourceCodeError = tryCatch(() => context.sourceCode);
     const reportError = tryCatch(() => context.report({ message: 'oh no', node: SPAN }));
 
     return {
@@ -35,6 +36,7 @@ const alwaysRunRule: Rule = {
         context.report({ message: `createOnce: filename: ${filenameError?.message}`, node: SPAN });
         context.report({ message: `createOnce: physicalFilename: ${physicalFilenameError?.message}`, node: SPAN });
         context.report({ message: `createOnce: options: ${optionsError?.message}`, node: SPAN });
+        context.report({ message: `createOnce: sourceCode: ${sourceCodeError?.message}`, node: SPAN });
         context.report({ message: `createOnce: report: ${reportError?.message}`, node: SPAN });
 
         context.report({ message: `before hook: id: ${context.id}`, node: SPAN });

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

@@ -0,0 +1,7 @@
+{
+  "jsPlugins": ["./plugin.ts"],
+  "categories": { "correctness": "off" },
+  "rules": {
+    "source-code-plugin/create": "error"
+  }
+}

apps/oxlint/test/fixtures/sourceCode/files/index.js

@@ -0,0 +1 @@
+let foo, bar;

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

@@ -0,0 +1,48 @@
+# Exit code
+1
+
+# stdout
+```
+  x source-code-plugin(create): create:
+  | source: "let foo, bar;\n"
+   ,-[files/index.js:1:1]
+ 1 | let foo, bar;
+   : ^
+   `----
+
+  x source-code-plugin(create): var decl:
+  | source: "let foo, bar;"
+   ,-[files/index.js:1:1]
+ 1 | let foo, bar;
+   : ^^^^^^^^^^^^^
+   `----
+
+  x source-code-plugin(create): ident "foo":
+  | source: "foo"
+  | source with before: "t foo"
+  | source with after: "foo,"
+  | source with both: "t foo,"
+   ,-[files/index.js:1:5]
+ 1 | let foo, bar;
+   :     ^^^
+   `----
+
+  x source-code-plugin(create): ident "bar":
+  | source: "bar"
+  | source with before: ", bar"
+  | source with after: "bar;"
+  | source with both: ", bar;"
+   ,-[files/index.js:1:10]
+ 1 | let foo, bar;
+   :          ^^^
+   `----
+
+Found 0 warnings and 4 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.
+```