Skip to content

Commit 4ec5168

Browse files
authored
feat: allow SourceCode#getText() to accept tokens and comments (#21340)
* feat: allow SourceCode#getText() to accept tokens and comments Fixes #21329 * refactor: remove redundant type declarations * docs: update descriptions of getLoc() and getRange() * docs: update JSDoc of getLoc() and getRange() * fix: align SourceCode declaration with runtime class
1 parent 5370d7e commit 4ec5168

5 files changed

Lines changed: 45 additions & 19 deletions

File tree

‎docs/src/extend/custom-rules.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,7 @@ module.exports = {
568568
569569
Once you have an instance of `SourceCode`, you can use the following methods on it to work with the code:
570570
571-
- `getText(node)`: Returns the source code for the given node. Omit `node` to get the whole source (see the [dedicated section](#accessing-the-source-text)).
571+
- `getText(node)`: Returns the source code for the given node, token, or comment. Omit the argument to get the whole source (see the [dedicated section](#accessing-the-source-text)).
572572
- `getAllComments()`: Returns an array of all comments in the source (see the [dedicated section](#accessing-comments)).
573573
- `getCommentsBefore(nodeOrToken)`: Returns an array of comment tokens that occur directly before the given node or token (see the [dedicated section](#accessing-comments)).
574574
- `getCommentsAfter(nodeOrToken)`: Returns an array of comment tokens that occur directly after the given node or token (see the [dedicated section](#accessing-comments)).
@@ -647,6 +647,12 @@ var source = sourceCode.getText();
647647
// get source for just this AST node
648648
var nodeSource = sourceCode.getText(node);
649649

650+
// get source for just this token
651+
var tokenSource = sourceCode.getText(token);
652+
653+
// get source for just this comment
654+
var commentSource = sourceCode.getText(comment);
655+
650656
// get source for AST node plus previous two characters
651657
var nodeSourceWithPrev = sourceCode.getText(node, 2);
652658

‎docs/src/extend/languages.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@ A basic `SourceCode` object must implement the following:
4242

4343
- `ast` - a property containing the AST or CST for the source code.
4444
- `text` - the text of the source code.
45-
- `getLoc(nodeOrToken)` - a method that returns the location of a given node or token. This must match the `loc` structure that ESTree uses.
46-
- `getRange(nodeOrToken)` - a method that returns the range of a given node or token. This must return an array where the first item is the start index and the second is the end index.
45+
- `getLoc(nodeOrToken)` - a method that returns the location of a given node, token, or comment. This must match the `loc` structure that ESTree uses.
46+
- `getRange(nodeOrToken)` - a method that returns the range of a given node, token, or comment. This must return an array where the first item is the start index and the second is the end index.
4747
- `traverse()` - a method that returns an iterable for traversing the AST or CST. The iterator must return objects that implement either `VisitTraversalStep` or `CallTraversalStep` from `@eslint/core`.
4848

4949
The following optional members allow you to customize how ESLint interacts with the object:
@@ -60,7 +60,7 @@ Additionally, the following members are common on `SourceCode` objects and are r
6060
- `lines` - the individual lines of the source code as an array of strings.
6161
- `getParent(node)` - returns the parent of the given node or `undefined` if the node is the root.
6262
- `getAncestors(node)` - returns an array of the ancestry of the node with the first item as the root of the tree and each subsequent item as the descendants of the root that lead to `node`.
63-
- `getText(node, beforeCount, afterCount)` - returns the string that represents the given node, and optionally, a specified number of characters before and after the node's range.
63+
- `getText(node, beforeCount, afterCount)` - returns the string that represents the given node, token, or comment, and optionally, a specified number of characters before and after its range.
6464

6565
See [`JSONSourceCode`](https://github.com/eslint/json/blob/main/src/languages/json-source-code.js) as an example of a basic `SourceCode` class.
6666

‎lib/languages/js/source-code/source-code.js‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -428,11 +428,11 @@ class SourceCode extends TokenStore {
428428
}
429429

430430
/**
431-
* Gets the source code for the given node.
432-
* @param {ASTNode} [node] The AST node to get the text for.
433-
* @param {number} [beforeCount] The number of characters before the node to retrieve.
434-
* @param {number} [afterCount] The number of characters after the node to retrieve.
435-
* @returns {string} The text representing the AST node.
431+
* Gets the source code for the given node, token, or comment.
432+
* @param {ASTNode|Token|Comment} [node] The node, token, or comment to get the text for.
433+
* @param {number} [beforeCount] The number of characters to retrieve before the node, token, or comment.
434+
* @param {number} [afterCount] The number of characters to retrieve after the node, token, or comment.
435+
* @returns {string} The text representing the node, token, or comment.
436436
* @public
437437
*/
438438
getText(node, beforeCount, afterCount) {
@@ -758,18 +758,18 @@ class SourceCode extends TokenStore {
758758
}
759759

760760
/**
761-
* Returns the location of the given node or token.
762-
* @param {ASTNode|Token} nodeOrToken The node or token to get the location of.
763-
* @returns {SourceLocation} The location of the node or token.
761+
* Returns the location of the given node, token, or comment.
762+
* @param {ASTNode|Token|Comment} nodeOrToken The node, token, or comment to get the location of.
763+
* @returns {SourceLocation} The location of the node, token, or comment.
764764
*/
765765
getLoc(nodeOrToken) {
766766
return nodeOrToken.loc;
767767
}
768768

769769
/**
770-
* Returns the range of the given node or token.
771-
* @param {ASTNode|Token} nodeOrToken The node or token to get the range of.
772-
* @returns {[number, number]} The range of the node or token.
770+
* Returns the range of the given node, token, or comment.
771+
* @param {ASTNode|Token|Comment} nodeOrToken The node, token, or comment to get the range of.
772+
* @returns {[number, number]} The range of the node, token, or comment.
773773
*/
774774
getRange(nodeOrToken) {
775775
return nodeOrToken.range;

‎lib/types/index.d.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ export namespace Scope {
240240
export class SourceCode implements TextSourceCode<{
241241
LangOptions: Linter.LanguageOptions;
242242
RootNode: AST.Program;
243-
SyntaxElementWithLoc: AST.Token | ESTree.Node;
243+
SyntaxElementWithLoc: AST.Token | ESTree.Node | ESTree.Comment;
244244
ConfigNode: ESTree.Comment;
245245
}> {
246246
text: string;
@@ -256,11 +256,15 @@ export class SourceCode implements TextSourceCode<{
256256

257257
static splitLines(text: string): string[];
258258

259-
getLoc(syntaxElement: AST.Token | ESTree.Node): ESTree.SourceLocation;
260-
getRange(syntaxElement: AST.Token | ESTree.Node): SourceRange;
259+
getLoc(
260+
syntaxElement: AST.Token | ESTree.Node | ESTree.Comment,
261+
): ESTree.SourceLocation;
262+
getRange(
263+
syntaxElement: AST.Token | ESTree.Node | ESTree.Comment,
264+
): SourceRange;
261265

262266
getText(
263-
node?: ESTree.Node,
267+
node?: ESTree.Node | AST.Token | ESTree.Comment,
264268
beforeCount?: number,
265269
afterCount?: number,
266270
): string;

‎tests/lib/types/types.test.mts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,13 @@ const COMMENT: Comment = {
9393

9494
// #region SourceCode
9595

96+
function findParent<Node extends object>(
97+
node: Node,
98+
getParent: (node: Node) => Node | undefined,
99+
) {
100+
return getParent(node);
101+
}
102+
96103
let sourceCode: SourceCode;
97104

98105
sourceCode = new SourceCode(SOURCE, AST);
@@ -141,13 +148,22 @@ sourceCode = new SourceCode({
141148
sourceCode = new SourceCode({ text: SOURCE, ast: AST, visitorKeys: null });
142149
sourceCode = new SourceCode({ text: SOURCE, ast: AST, visitorKeys: undefined });
143150

151+
const sourceCodeWithPublicMembers: Pick<SourceCode, keyof SourceCode> =
152+
sourceCode;
153+
sourceCode = sourceCodeWithPublicMembers;
154+
144155
SourceCode.splitLines(SOURCE);
145156

146157
sourceCode.getText();
147158
sourceCode.getText(AST);
159+
sourceCode.getText(TOKEN);
160+
sourceCode.getText(COMMENT);
148161
sourceCode.getText(AST, 0);
149162
sourceCode.getText(AST, 0, 0);
150163

164+
// @ts-expect-error SourceCode does not have a `getParent` method
165+
findParent(AST, sourceCode.getParent);
166+
151167
sourceCode.getLines();
152168

153169
sourceCode.getAllComments();

0 commit comments

Comments
 (0)