feat!: Add getLoc/getRange to SourceCode interface (#89)

Author: nzakas

packages/core/src/types.ts

@@ -31,12 +31,11 @@ export interface FileProblem {
 //------------------------------------------------------------------------------
 
 /**
- * Represents an AST node or token with location information.
+ * Represents an AST node or token with location information in ESLint format.
  */
 export interface SyntaxElement {
 	loc: SourceLocation;
-	range: [number, number];
-	[key: string]: any;
+	range: SourceRange;
 }
 
 /**
@@ -48,13 +47,34 @@ export interface SourceLocation {
 }
 
 /**
- * Represents a location coordinate inside the source.
+ * Represents the start and end coordinates of a node inside the source with an offset.
+ */
+export interface SourceLocationWithOffset {
+	start: PositionWithOffset;
+	end: PositionWithOffset;
+}
+
+/**
+ * Represents a location coordinate inside the source. ESLint-style formats
+ * have just `line` and `column` while others may have `offset` as well.
  */
 export interface Position {
 	line: number;
 	column: number;
 }
 
+/**
+ * Represents a location coordinate inside the source with an offset.
+ */
+export interface PositionWithOffset extends Position {
+	offset: number;
+}
+
+/**
+ * Represents a range of characters in the source.
+ */
+export type SourceRange = [number, number];
+
 //------------------------------------------------------------------------------
 // Config
 //------------------------------------------------------------------------------
@@ -157,8 +177,8 @@ export interface Language {
 	 */
 	matchesSelectorClass?(
 		className: string,
-		node: SyntaxElement,
-		ancestry: Array<SyntaxElement>,
+		node: object,
+		ancestry: Array<object>,
 	): boolean;
 
 	/**
@@ -222,7 +242,7 @@ export interface File {
 /**
  * Represents the successful result of parsing a file.
  */
-export interface OkParseResult {
+export interface OkParseResult<T extends object = object> {
 	/**
 	 * Indicates if the parse was successful. If true, the parse was successful
 	 * and ESLint should continue on to create a SourceCode object and run rules;
@@ -234,7 +254,7 @@ export interface OkParseResult {
 	/**
 	 * The abstract syntax tree created by the parser. (only when ok: true)
 	 */
-	ast: SyntaxElement;
+	ast: T;
 
 	/**
 	 * Any additional data that the parser wants to provide.
@@ -265,7 +285,9 @@ export interface NotOkParseResult {
 	[key: string]: any;
 }
 
-export type ParseResult = OkParseResult | NotOkParseResult;
+export type ParseResult<T extends object = object> =
+	| OkParseResult<T>
+	| NotOkParseResult;
 
 /**
  * Represents inline configuration found in the source code.
@@ -291,7 +313,7 @@ interface SourceCodeBase {
 	/**
 	 * Root of the AST.
 	 */
-	ast: SyntaxElement;
+	ast: object;
 
 	/**
 	 * The traversal path that tools should take when evaluating the AST.
@@ -300,6 +322,16 @@ interface SourceCodeBase {
 	 */
 	visitorKeys?: Record<string, Array<string>>;
 
+	/**
+	 * Retrieves the equivalent of `loc` for a given node or token.
+	 */
+	getLoc(nodeOrToken: object): SourceLocation;
+
+	/**
+	 * Retrieves the equivalent of `range` for a given node or token.
+	 */
+	getRange(nodeOrToken: object): SourceRange;
+
 	/**
 	 * Traversal of AST.
 	 */
@@ -323,7 +355,7 @@ interface SourceCodeBase {
 	 * Returns an array of all inline configuration nodes found in the
 	 * source code.
 	 */
-	getInlineConfigNodes?(): Array<SyntaxElement>;
+	getInlineConfigNodes?(): Array<object>;
 
 	/**
 	 * Applies configuration found inside of the source code. This method is only
@@ -370,7 +402,7 @@ export type SourceCode = TextSourceCode | BinarySourceCode;
  */
 export interface VisitTraversalStep {
 	kind: 1;
-	target: SyntaxElement;
+	target: object;
 	phase: 1 /* enter */ | 2 /* exit */;
 	args: Array<any>;
 }
@@ -399,7 +431,7 @@ export interface Directive {
 	/**
 	 * The node of the directive. May be in the AST or a comment/token.
 	 */
-	node: SyntaxElement;
+	node: object;
 
 	/**
 	 * The value of the directive.