feat(linter/plugins): add loc field getter to all AST nodes (#14355)

Add `loc` to all AST nodes.

`loc` is computed lazily, as it's quite an expensive operation - because it requires searching the source text for line breaks and building a translation table.

We can consider making `loc` a "real" property once we have a faster translation table built on Rust side.

Author: overlookmotel

.github/generated/ast_changes_watch_list.yml

@@ -76,8 +76,8 @@ src:
   - 'napi/parser/generated/deserialize/ts.js'
   - 'napi/parser/generated/deserialize/ts_parent.js'
   - 'napi/parser/generated/deserialize/ts_range.js'
+  - 'napi/parser/generated/deserialize/ts_range_loc_parent_no_parens.js'
   - 'napi/parser/generated/deserialize/ts_range_parent.js'
-  - 'napi/parser/generated/deserialize/ts_range_parent_no_parens.js'
   - 'napi/parser/generated/lazy/constructors.js'
   - 'napi/parser/generated/lazy/types.js'
   - 'napi/parser/generated/lazy/walk.js'

apps/oxlint/scripts/build.js

@@ -32,7 +32,7 @@ const parserFilePaths = [
   'generated/lazy/types.js',
   'generated/lazy/walk.js',
   */
-  'generated/deserialize/ts_range_parent_no_parens.js',
+  'generated/deserialize/ts_range_loc_parent_no_parens.js',
   'generated/visit/keys.js',
   'generated/visit/types.js',
   'generated/visit/walk.js',

apps/oxlint/src-js/generated/types.d.ts

@@ -1,6 +1,9 @@
 // Auto-generated code, DO NOT EDIT DIRECTLY!
 // To edit this generated file you have to edit `tasks/ast_tools/src/generators/typescript.rs`.
 
+import { Span } from '../plugins/types.ts';
+export { Span };
+
 export interface Program extends Span {
   type: 'Program';
   body: Array<Directive | Statement>;
@@ -1701,12 +1704,6 @@ export type UnaryOperator = '+' | '-' | '!' | '~' | 'typeof' | 'void' | 'delete'
 
 export type UpdateOperator = '++' | '--';
 
-export interface Span {
-  start: number;
-  end: number;
-  range: [number, number];
-}
-
 export type ModuleKind = 'script' | 'module';
 
 export type Node =

apps/oxlint/src-js/index.ts

@@ -27,6 +27,7 @@ export type {
   Range,
   Ranged,
   RuleMeta,
+  Span,
   Token,
   Visitor,
   VisitorWithHooks,

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

@@ -1,6 +1,8 @@
 import { initSourceText, sourceText } from './source_code.js';
 
-import type { LineColumn } from './types.ts';
+import type { LineColumn, Location, Node } from './types.ts';
+
+const { defineProperty } = Object;
 
 // Pattern for splitting source text into lines
 const LINE_BREAK_PATTERN = /\r\n|[\r\n\u2028\u2029]/gu;
@@ -69,6 +71,18 @@ export function getLineColumnFromOffset(offset: number): LineColumn {
     );
   }
 
+  return getLineColumnFromOffsetUnchecked(offset);
+}
+
+/**
+ * Convert a source text index into a (line, column) pair without:
+ * 1. Checking type of `offset`, or that it's in range.
+ * 2. Initializing `lineStartOffsets`. Caller must do that before calling this method.
+ *
+ * @param offset - The index of a character in a file.
+ * @returns `{line, column}` location object with 1-indexed line and 0-indexed column.
+ */
+function getLineColumnFromOffsetUnchecked(offset: number): LineColumn {
   // Binary search `lineStartOffsets` for the line containing `offset`
   let low = 0, high = lineStartOffsets.length, mid: number;
   do {
@@ -138,3 +152,30 @@ export function getOffsetFromLineColumn(loc: LineColumn): number {
 
   throw new TypeError('Expected `loc` to be an object with integer `line` and `column` properties.');
 }
+
+/**
+ * Get the `Location` for an AST node. Used in `loc` getters on AST nodes.
+ *
+ * Overwrites the `loc` getter with the calculated `Location`, so accessing `loc` twice on same node
+ * results in the same object each time.
+ *
+ * For internal use only.
+ *
+ * @param node - AST node object
+ * @returns Location
+ */
+export function getNodeLoc(node: Node): Location {
+  // Build `lines` and `lineStartOffsets` tables if they haven't been already.
+  // This also decodes `sourceText` if it wasn't already.
+  if (lines.length === 0) initLines();
+
+  const loc = {
+    start: getLineColumnFromOffsetUnchecked(node.start),
+    end: getLineColumnFromOffsetUnchecked(node.end),
+  };
+
+  // Replace `loc` getter with the calculated value
+  defineProperty(node, 'loc', { value: loc, writable: true });
+
+  return loc;
+}

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

@@ -6,9 +6,18 @@ import {
   // @ts-expect-error
 } from '../generated/constants.js';
 // @ts-expect-error we need to generate `.d.ts` file for this module
-// We use the deserializer which removes `ParenthesizedExpression`s from AST to match ESLint
-import { deserializeProgramOnly } from '../../dist/generated/deserialize/ts_range_parent_no_parens.js';
-import { getLineColumnFromOffset, getOffsetFromLineColumn, initLines, lines, resetLines } from './location.js';
+// We use the deserializer which removes `ParenthesizedExpression`s from AST,
+// and with `range`, `loc`, and `parent` properties on AST nodes, to match ESLint
+import { deserializeProgramOnly } from '../../dist/generated/deserialize/ts_range_loc_parent_no_parens.js';
+
+import {
+  getLineColumnFromOffset,
+  getNodeLoc,
+  getOffsetFromLineColumn,
+  initLines,
+  lines,
+  resetLines,
+} from './location.js';
 
 import type { Program } from '../generated/types.d.ts';
 import type { Scope, ScopeManager, Variable } from './scope.ts';
@@ -61,7 +70,7 @@ export function initSourceText(): void {
  */
 export function initAst(): void {
   if (sourceText === null) initSourceText();
-  ast = deserializeProgramOnly(buffer, sourceText, sourceByteLen);
+  ast = deserializeProgramOnly(buffer, sourceText, sourceByteLen, getNodeLoc);
 }
 
 /**

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

@@ -25,21 +25,21 @@ export interface VisitorWithHooks extends Visitor {
 // Visit function for a specific AST node type.
 export type VisitFn = (node: Node) => void;
 
+// Range of source offsets.
+export type Range = [number, number];
+
 // Interface for any type which has `range` field
 export interface Ranged {
   range: Range;
 }
 
-// Internal interface for any type which has location properties.
-interface Spanned extends Ranged {
+// Interface for any type which has location properties.
+export interface Span extends Ranged {
   start: number;
   end: number;
-  loc?: Location;
+  loc: Location;
 }
 
-// Range of source offsets.
-export type Range = [number, number];
-
 // Source code location.
 export interface Location {
   start: LineColumn;
@@ -54,10 +54,10 @@ export interface LineColumn {
 }
 
 // AST node type.
-export interface Node extends Spanned {}
+export interface Node extends Span {}
 
 // AST token type.
-export interface Token extends Spanned {
+export interface Token extends Span {
   type: string;
   value: string;
 }
@@ -66,7 +66,7 @@ export interface Token extends Spanned {
 export type NodeOrToken = Node | Token;
 
 // Comment.
-export interface Comment extends Spanned {
+export interface Comment extends Span {
   type: 'Line' | 'Block';
   value: string;
 }

apps/oxlint/test/compile-visitor.test.ts

@@ -20,7 +20,15 @@ import type { EnterExit, Node, VisitFn } from '../src-js/plugins/types.ts';
 const PROGRAM_TYPE_ID = NODE_TYPE_IDS_MAP.get('Program'),
   EMPTY_STMT_TYPE_ID = NODE_TYPE_IDS_MAP.get('EmptyStatement');
 
-const SPAN: Node = { start: 0, end: 0, range: [0, 0] };
+const SPAN: Node = {
+  start: 0,
+  end: 0,
+  range: [0, 0],
+  loc: {
+    start: { line: 0, column: 0 },
+    end: { line: 0, column: 0 },
+  },
+};
 
 describe('compile visitor', () => {
   beforeEach(initCompiledVisitor);

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

@@ -2,7 +2,15 @@ import { sep } from 'node:path';
 
 import type { Node, Plugin, Rule } from '../../../dist/index.js';
 
-const SPAN: Node = { start: 0, end: 0, range: [0, 0] };
+const SPAN: Node = {
+  start: 0,
+  end: 0,
+  range: [0, 0],
+  loc: {
+    start: { line: 0, column: 0 },
+    end: { line: 0, column: 0 },
+  },
+};
 
 const DIR_PATH_LEN = import.meta.dirname.length + 1;
 

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

@@ -2,7 +2,15 @@ import { sep } from 'node:path';
 
 import type { Node, Plugin, Rule } from '../../../dist/index.js';
 
-const SPAN: Node = { start: 0, end: 0, range: [0, 0] };
+const SPAN: Node = {
+  start: 0,
+  end: 0,
+  range: [0, 0],
+  loc: {
+    start: { line: 0, column: 0 },
+    end: { line: 0, column: 0 },
+  },
+};
 
 const DIR_PATH_LEN = import.meta.dirname.length + 1;