[7.x backport] feat: Allow specifying startLine in code frame (#17739)

Copilot · liuxingbaoyu · web-flow · commit ad0d03f0c924 · 2026-01-29T19:44:22.000+01:00
Co-authored-by: liuxingbaoyu &lt;30521560+liuxingbaoyu@users.noreply.github.com&gt;
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
diff --git a/packages/babel-code-frame/src/index.ts b/packages/babel-code-frame/src/index.ts
@@ -22,6 +22,8 @@ export interface Options {
   linesAbove?: number;
   /**  The number of lines to show below the error. default: 3 */
   linesBelow?: number;
+  /** The line number corresponding to the first line in `rawLines`. default: 1 */
+  startLine?: number;
   /**
    * Forcibly syntax highlight the code as JavaScript (for non-terminals);
    * overrides highlightCode.
@@ -53,6 +55,7 @@ function getMarkerLines(
   loc: NodeLocation,
   source: string[],
   opts: Options,
+  startLineBaseZero: number,
 ): {
   start: number;
   end: number;
@@ -68,9 +71,9 @@ function getMarkerLines(
     ...loc.end,
   };
   const { linesAbove = 2, linesBelow = 3 } = opts || {};
-  const startLine = startLoc.line;
+  const startLine = startLoc.line - startLineBaseZero;
   const startColumn = startLoc.column;
-  const endLine = endLoc.line;
+  const endLine = endLoc.line - startLineBaseZero;
   const endColumn = endLoc.column;
 
   let start = Math.max(startLine - (linesAbove + 1), 0);
@@ -127,13 +130,19 @@ export function codeFrameColumns(
 ): string {
   const shouldHighlight =
     opts.forceColor || (isColorSupported() && opts.highlightCode);
+  const startLineBaseZero = (opts.startLine || 1) - 1;
   const defs = getDefs(shouldHighlight);
 
   const lines = rawLines.split(NEWLINE);
-  const { start, end, markerLines } = getMarkerLines(loc, lines, opts);
+  const { start, end, markerLines } = getMarkerLines(
+    loc,
+    lines,
+    opts,
+    startLineBaseZero,
+  );
   const hasColumns = loc.start && typeof loc.start.column === "number";
 
-  const numberMaxWidth = String(end).length;
+  const numberMaxWidth = String(end + startLineBaseZero).length;
 
   const highlightedLines = shouldHighlight ? highlight(rawLines) : rawLines;
 
@@ -142,7 +151,9 @@ export function codeFrameColumns(
     .slice(start, end)
     .map((line, index) => {
       const number = start + 1 + index;
-      const paddedNumber = ` ${number}`.slice(-numberMaxWidth);
+      const paddedNumber = ` ${number + startLineBaseZero}`.slice(
+        -numberMaxWidth,
+      );
       const gutter = ` ${paddedNumber} |`;
       const hasMarker = markerLines[number];
       const lastMarkerLine = !markerLines[number + 1];
diff --git a/packages/babel-code-frame/test/index.js b/packages/babel-code-frame/test/index.js
@@ -420,4 +420,14 @@ describe("@babel/code-frame", function () {
     expect(stripAnsi(highlighted)).toBe(raw);
     expect(highlighted.length).toBeGreaterThan(raw.length);
   });
+
+  test("opts.startLine", function () {
+    const rawLines = "const a = 1;\nconst b = 1";
+    expect(
+      codeFrameColumns(rawLines, { start: { line: 102 } }, { startLine: 101 }),
+    ).toMatchInlineSnapshot(`
+      "  101 | const a = 1;
+      > 102 | const b = 1"
+    `);
+  });
 });
diff --git a/packages/babel-core/src/parser/index.ts b/packages/babel-core/src/parser/index.ts
@@ -50,6 +50,13 @@ export default function* parser(
       // err.code will be changed to BABEL_PARSE_ERROR later.
     }
 
+    const startLine = parserOpts?.startLine;
+    const startColumn = parserOpts?.startColumn;
+
+    if (startColumn != null) {
+      code = " ".repeat(startColumn) + code;
+    }
+
     const { loc, missingPlugin } = err;
     if (loc) {
       const codeFrame = codeFrameColumns(
@@ -62,6 +69,7 @@ export default function* parser(
         },
         {
           highlightCode,
+          startLine,
         },
       );
       if (missingPlugin) {
diff --git a/packages/babel-core/test/parse.js b/packages/babel-core/test/parse.js
@@ -39,4 +39,28 @@ describe("parseSync", function () {
     });
     expect(JSON.parse(JSON.stringify(result))).toEqual(output);
   });
+
+  it("should show correct codeFrame with startLine and startColumn", function () {
+    const input = `const* a = 1;`;
+    let err;
+    try {
+      parseSync(input, {
+        parserOpts: {
+          startLine: 3,
+          startColumn: 3,
+        },
+        highlightCode: false,
+        configFile: false,
+        babelrc: false,
+      });
+    } catch (e) {
+      err = e;
+    }
+    expect(err.message).toMatchInlineSnapshot(`
+      "unknown: Unexpected token (3:8)
+
+      > 3 |    const* a = 1;
+          |         ^"
+    `);
+  });
 });
