Skip to content

feat(linter/plugins): implement SourceCode#getIndexFromLoc and getLocFromIndex #14303

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 2, 2025
Merged

feat(linter/plugins): implement SourceCode#getIndexFromLoc and getLocFromIndex #14303

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 93 additions & 22 deletions apps/oxlint/src-js/plugins/source_code.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -506,28 +506,8 @@ export const SOURCE_CODE = Object.freeze({
throw new Error('`sourceCode.getNodeByRangeIndex` not implemented yet'); // TODO
},

/**
* Convert a source text index into a (line, column) pair.
* @param index The index of a character in a file.
* @returns `{line, column}` location object with 1-indexed line and 0-indexed column.
* @throws {TypeError|RangeError} If non-numeric `index`, or `index` out of range.
*/
// oxlint-disable-next-line no-unused-vars
getLocFromIndex(index: number): LineColumn {
throw new Error('`sourceCode.getLocFromIndex` not implemented yet'); // TODO
},

/**
* Convert a `{ line, column }` pair into a range index.
* @param loc - A line/column location.
* @returns The range index of the location in the file.
* @throws {TypeError|RangeError} If `loc` is not an object with a numeric `line` and `column`,
* or if the `line` is less than or equal to zero, or the line or column is out of the expected range.
*/
// oxlint-disable-next-line no-unused-vars
getIndexFromLoc(loc: LineColumn): number {
throw new Error('`sourceCode.getIndexFromLoc` not implemented yet'); // TODO
},
getLocFromIndex,
getIndexFromLoc,

/**
* Check whether any comments exist or not between the given 2 nodes.
Expand Down Expand Up @@ -586,6 +566,97 @@ export const SOURCE_CODE = Object.freeze({

export type SourceCode = typeof SOURCE_CODE;

/**
* Convert a source text index into a (line, column) pair.
* @param offset The index of a character in a file.
* @returns `{line, column}` location object with 1-indexed line and 0-indexed column.
* @throws {TypeError|RangeError} If non-numeric `index`, or `index` out of range.
*/
function getLocFromIndex(offset: number): LineColumn {
if (typeof offset !== 'number' || offset < 0 || (offset | 0) !== offset) {
throw new TypeError('Expected `offset` to be a non-negative integer.');
}

// 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();

if (offset > sourceText.length) {
throw new RangeError(
`Index out of range (requested index ${offset}, but source text has length ${sourceText.length}).`,
);
}

// Binary search `lineStartOffsets` for the line containing `offset`
let low = 0, high = lineStartOffsets.length, mid: number;
do {
mid = ((low + high) / 2) | 0; // Use bitwise OR to floor the division
if (offset < lineStartOffsets[mid]) {
high = mid;
} else {
low = mid + 1;
}
} while (low < high);

return { line: low, column: offset - lineStartOffsets[low - 1] };
}

/**
* Convert a `{ line, column }` pair into a range index.
* @param loc - A line/column location.
* @returns The range index of the location in the file.
* @throws {TypeError|RangeError} If `loc` is not an object with a numeric `line` and `column`,
* or if the `line` is less than or equal to zero, or the line or column is out of the expected range.
*/
function getIndexFromLoc(loc: LineColumn): number {
if (loc !== null && typeof loc === 'object') {
const { line, column } = loc;
if (typeof line === 'number' && typeof column === 'number' && (line | 0) === line && (column | 0) === column) {
// 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 linesCount = lineStartOffsets.length;
if (line <= 0 || line > linesCount) {
throw new RangeError(
`Line number out of range (line ${line} requested). ` +
`Line numbers should be 1-based, and less than or equal to number of lines in file (${linesCount}).`,
);
}
if (column < 0) throw new RangeError(`Invalid column number (column ${column} requested).`);

const lineOffset = lineStartOffsets[line - 1];
const offset = lineOffset + column;

// Comment from ESLint implementation:
/*
* By design, `getIndexFromLoc({ line: lineNum, column: 0 })` should return the start index of
* the given line, provided that the line number is valid element of `lines`. Since the
* last element of `lines` is an empty string for files with trailing newlines, add a
* special case where getting the index for the first location after the end of the file
* will return the length of the file, rather than throwing an error. This allows rules to
* use `getIndexFromLoc` consistently without worrying about edge cases at the end of a file.
*/

let nextLineOffset;
if (line === linesCount) {
nextLineOffset = sourceText.length;
if (offset <= nextLineOffset) return offset;
} else {
nextLineOffset = lineStartOffsets[line];
if (offset < nextLineOffset) return offset;
}

throw new RangeError(
`Column number out of range (column ${column} requested, ` +
`but the length of line ${line} is ${nextLineOffset - lineOffset}).`,
);
}
}

throw new TypeError('Expected `loc` to be an object with integer `line` and `column` properties.');
}

// Options for various `SourceCode` methods e.g. `getFirstToken`.
export interface SkipOptions {
// Number of skipping tokens
Expand Down
88 changes: 88 additions & 0 deletions apps/oxlint/test/fixtures/sourceCode/output.snap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,33 @@
| text: "let foo, bar;\n\n// x\n// y\n"
| getText(): "let foo, bar;\n\n// x\n// y\n"
| lines: ["let foo, bar;","","// x","// y",""]
| locs:
| 0 => { line: 1, column: 0 }("l")
| 1 => { line: 1, column: 1 }("e")
| 2 => { line: 1, column: 2 }("t")
| 3 => { line: 1, column: 3 }(" ")
| 4 => { line: 1, column: 4 }("f")
| 5 => { line: 1, column: 5 }("o")
| 6 => { line: 1, column: 6 }("o")
| 7 => { line: 1, column: 7 }(",")
| 8 => { line: 1, column: 8 }(" ")
| 9 => { line: 1, column: 9 }("b")
| 10 => { line: 1, column: 10 }("a")
| 11 => { line: 1, column: 11 }("r")
| 12 => { line: 1, column: 12 }(";")
| 13 => { line: 1, column: 13 }("\n")
| 14 => { line: 2, column: 0 }("\n")
| 15 => { line: 3, column: 0 }("/")
| 16 => { line: 3, column: 1 }("/")
| 17 => { line: 3, column: 2 }(" ")
| 18 => { line: 3, column: 3 }("x")
| 19 => { line: 3, column: 4 }("\n")
| 20 => { line: 4, column: 0 }("/")
| 21 => { line: 4, column: 1 }("/")
| 22 => { line: 4, column: 2 }(" ")
| 23 => { line: 4, column: 3 }("y")
| 24 => { line: 4, column: 4 }("\n")
| 25 => { line: 5, column: 0 }("<EOF>")
| ast: "foo"
| visitorKeys: left, right
,-[files/1.js:1:1]
Expand All @@ -27,6 +54,33 @@
| text: "let foo, bar;\n\n// x\n// y\n"
| getText(): "let foo, bar;\n\n// x\n// y\n"
| lines: ["let foo, bar;","","// x","// y",""]
| locs:
| 0 => { line: 1, column: 0 }("l")
| 1 => { line: 1, column: 1 }("e")
| 2 => { line: 1, column: 2 }("t")
| 3 => { line: 1, column: 3 }(" ")
| 4 => { line: 1, column: 4 }("f")
| 5 => { line: 1, column: 5 }("o")
| 6 => { line: 1, column: 6 }("o")
| 7 => { line: 1, column: 7 }(",")
| 8 => { line: 1, column: 8 }(" ")
| 9 => { line: 1, column: 9 }("b")
| 10 => { line: 1, column: 10 }("a")
| 11 => { line: 1, column: 11 }("r")
| 12 => { line: 1, column: 12 }(";")
| 13 => { line: 1, column: 13 }("\n")
| 14 => { line: 2, column: 0 }("\n")
| 15 => { line: 3, column: 0 }("/")
| 16 => { line: 3, column: 1 }("/")
| 17 => { line: 3, column: 2 }(" ")
| 18 => { line: 3, column: 3 }("x")
| 19 => { line: 3, column: 4 }("\n")
| 20 => { line: 4, column: 0 }("/")
| 21 => { line: 4, column: 1 }("/")
| 22 => { line: 4, column: 2 }(" ")
| 23 => { line: 4, column: 3 }("y")
| 24 => { line: 4, column: 4 }("\n")
| 25 => { line: 5, column: 0 }("<EOF>")
| ast: "foo"
| visitorKeys: left, right
,-[files/1.js:1:1]
Expand Down Expand Up @@ -56,6 +110,8 @@
| source with before: "t foo"
| source with after: "foo,"
| source with both: "t foo,"
| start loc: {"line":1,"column":4}
| end loc: {"line":1,"column":7}
,-[files/1.js:1:5]
1 | let foo, bar;
: ^^^
Expand All @@ -67,6 +123,8 @@
| source with before: "t foo"
| source with after: "foo,"
| source with both: "t foo,"
| start loc: {"line":1,"column":4}
| end loc: {"line":1,"column":7}
,-[files/1.js:1:5]
1 | let foo, bar;
: ^^^
Expand All @@ -78,6 +136,8 @@
| source with before: ", bar"
| source with after: "bar;"
| source with both: ", bar;"
| start loc: {"line":1,"column":9}
| end loc: {"line":1,"column":12}
,-[files/1.js:1:10]
1 | let foo, bar;
: ^^^
Expand All @@ -89,6 +149,8 @@
| source with before: ", bar"
| source with after: "bar;"
| source with both: ", bar;"
| start loc: {"line":1,"column":9}
| end loc: {"line":1,"column":12}
,-[files/1.js:1:10]
1 | let foo, bar;
: ^^^
Expand All @@ -99,6 +161,17 @@
| text: "let qux;\n"
| getText(): "let qux;\n"
| lines: ["let qux;",""]
| locs:
| 0 => { line: 1, column: 0 }("l")
| 1 => { line: 1, column: 1 }("e")
| 2 => { line: 1, column: 2 }("t")
| 3 => { line: 1, column: 3 }(" ")
| 4 => { line: 1, column: 4 }("q")
| 5 => { line: 1, column: 5 }("u")
| 6 => { line: 1, column: 6 }("x")
| 7 => { line: 1, column: 7 }(";")
| 8 => { line: 1, column: 8 }("\n")
| 9 => { line: 2, column: 0 }("<EOF>")
| ast: "qux"
| visitorKeys: left, right
,-[files/2.js:1:1]
Expand All @@ -117,6 +190,17 @@
| text: "let qux;\n"
| getText(): "let qux;\n"
| lines: ["let qux;",""]
| locs:
| 0 => { line: 1, column: 0 }("l")
| 1 => { line: 1, column: 1 }("e")
| 2 => { line: 1, column: 2 }("t")
| 3 => { line: 1, column: 3 }(" ")
| 4 => { line: 1, column: 4 }("q")
| 5 => { line: 1, column: 5 }("u")
| 6 => { line: 1, column: 6 }("x")
| 7 => { line: 1, column: 7 }(";")
| 8 => { line: 1, column: 8 }("\n")
| 9 => { line: 2, column: 0 }("<EOF>")
| ast: "qux"
| visitorKeys: left, right
,-[files/2.js:1:1]
Expand All @@ -143,6 +227,8 @@
| source with before: "t qux"
| source with after: "qux;"
| source with both: "t qux;"
| start loc: {"line":1,"column":4}
| end loc: {"line":1,"column":7}
,-[files/2.js:1:5]
1 | let qux;
: ^^^
Expand All @@ -153,6 +239,8 @@
| source with before: "t qux"
| source with after: "qux;"
| source with both: "t qux;"
| start loc: {"line":1,"column":4}
| end loc: {"line":1,"column":7}
,-[files/2.js:1:5]
1 | let qux;
: ^^^
Expand Down
47 changes: 40 additions & 7 deletions apps/oxlint/test/fixtures/sourceCode/plugin.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,22 @@ const SPAN = { start: 0, end: 0 };

const createRule: Rule = {
create(context) {
const { ast } = context.sourceCode;
const { ast, lines, text } = context.sourceCode;

let locs = '';
for (let offset = 0; offset <= text.length; offset++) {
const loc = context.sourceCode.getLocFromIndex(offset);
assert(context.sourceCode.getIndexFromLoc(loc) === offset);
locs += `\n ${offset} => { line: ${loc.line}, column: ${loc.column} }` +
`(${JSON.stringify(text[offset] || '<EOF>')})`;
}

context.report({
message: 'create:\n' +
`text: ${JSON.stringify(context.sourceCode.text)}\n` +
`text: ${JSON.stringify(text)}\n` +
`getText(): ${JSON.stringify(context.sourceCode.getText())}\n` +
`lines: ${JSON.stringify(context.sourceCode.lines)}\n` +
`lines: ${JSON.stringify(lines)}\n` +
`locs:${locs}\n` +
// @ts-ignore
`ast: "${ast.body[0].declarations[0].id.name}"\n` +
`visitorKeys: ${context.sourceCode.visitorKeys.BinaryExpression.join(', ')}`,
Expand All @@ -31,12 +40,19 @@ const createRule: Rule = {
});
},
Identifier(node) {
const startLoc = context.sourceCode.getLocFromIndex(node.start);
const endLoc = context.sourceCode.getLocFromIndex(node.end);
assert(context.sourceCode.getIndexFromLoc(startLoc) === node.start);
assert(context.sourceCode.getIndexFromLoc(endLoc) === node.end);

context.report({
message: `ident "${node.name}":\n` +
`source: "${context.sourceCode.getText(node)}"\n` +
`source with before: "${context.sourceCode.getText(node, 2)}"\n` +
`source with after: "${context.sourceCode.getText(node, null, 1)}"\n` +
`source with both: "${context.sourceCode.getText(node, 2, 1)}"`,
`source with both: "${context.sourceCode.getText(node, 2, 1)}"\n` +
`start loc: ${JSON.stringify(startLoc)}\n` +
`end loc: ${JSON.stringify(endLoc)}`,
node,
});
},
Expand All @@ -51,12 +67,22 @@ const createOnceRule: Rule = {
return {
before() {
ast = context.sourceCode.ast;
const { lines, text } = context.sourceCode;

let locs = '';
for (let offset = 0; offset <= text.length; offset++) {
const loc = context.sourceCode.getLocFromIndex(offset);
assert(context.sourceCode.getIndexFromLoc(loc) === offset);
locs += `\n ${offset} => { line: ${loc.line}, column: ${loc.column} }` +
`(${JSON.stringify(text[offset] || '<EOF>')})`;
}

context.report({
message: 'before:\n' +
`text: ${JSON.stringify(context.sourceCode.text)}\n` +
`text: ${JSON.stringify(text)}\n` +
`getText(): ${JSON.stringify(context.sourceCode.getText())}\n` +
`lines: ${JSON.stringify(context.sourceCode.lines)}\n` +
`lines: ${JSON.stringify(lines)}\n` +
`locs:${locs}\n` +
// @ts-ignore
`ast: "${ast.body[0].declarations[0].id.name}"\n` +
`visitorKeys: ${context.sourceCode.visitorKeys.BinaryExpression.join(', ')}`,
Expand All @@ -73,12 +99,19 @@ const createOnceRule: Rule = {
});
},
Identifier(node) {
const startLoc = context.sourceCode.getLocFromIndex(node.start);
const endLoc = context.sourceCode.getLocFromIndex(node.end);
assert(context.sourceCode.getIndexFromLoc(startLoc) === node.start);
assert(context.sourceCode.getIndexFromLoc(endLoc) === node.end);

context.report({
message: `ident "${node.name}":\n` +
`source: "${context.sourceCode.getText(node)}"\n` +
`source with before: "${context.sourceCode.getText(node, 2)}"\n` +
`source with after: "${context.sourceCode.getText(node, null, 1)}"\n` +
`source with both: "${context.sourceCode.getText(node, 2, 1)}"`,
`source with both: "${context.sourceCode.getText(node, 2, 1)}"\n` +
`start loc: ${JSON.stringify(startLoc)}\n` +
`end loc: ${JSON.stringify(endLoc)}`,
node,
});
},
Expand Down
Loading