feat: allow for overriding of file and or line

Rather than extracting these from the trace. Useful where the file might be "<exec>" in Pyodide.

Author: grega

README.md

@@ -50,6 +50,14 @@ if (result) {
   // no friendly explanation — show the original traceback as-is
 }
 
+// if the trace reports an unhelpful source location (eg. Pyodide runs code as "<exec>"), pass file explicitly to override what's parsed from the trace:
+const result = friendlyExplain({
+  error: rawTracebackString,
+  code: editorCode,
+  runtime: "pyodide",
+  file: "main.py", // overrides the file from the trace
+});
+
 // optionally limit which sections appear in result.html:
 const result = friendlyExplain({
   error: rawTracebackString,

src/engine.ts

@@ -148,9 +148,19 @@ export const friendlyExplain = (opts: ExplainOptions): ExplainResult | null => {
   // The error could not be parsed — no friendly explanation; caller uses the raw error.
   if (!trace) return null;
 
-  if (code && trace.line && !trace.codeLine) {
+  // Caller-provided file/line take precedence over whatever was parsed from the trace
+  // Useful when the traceback's innermost frame references an internal file (eg.
+  // Pyodide's "<exec>") instead of the user's filename, or when the line needs correcting.
+  if (opts.file !== undefined) trace.file = opts.file;
+  if (opts.line !== undefined) trace.line = opts.line;
+
+  // (Re)derive the code context from the effective line: when the caller overrides the
+  // line, or when a pre-parsed trace arrived without a codeLine.
+  if (code && trace.line && (opts.line !== undefined || !trace.codeLine)) {
     const lines = code.split(/\r?\n/);
     trace.codeLine = lines[trace.line - 1]?.trim();
+    trace.codeBefore = lines.slice(Math.max(0, trace.line - 3), trace.line - 1);
+    trace.codeAfter = lines.slice(trace.line, trace.line + 2);
   }
 
   const chosen = pickVariant(trace, code, opts.sections);

src/types.ts

@@ -22,6 +22,14 @@ export type Section = "title" | "summary" | "why" | "steps" | "patch" | "details
 export type ExplainOptions = {
   error: string | Error | Trace;
   code?: string;
+  /**
+   * Override the source file, instead of using the one parsed from the trace.
+   * Useful when the traceback's innermost frame references an internal file
+   * (eg. Pyodide's "<exec>") rather than the user's filename.
+   */
+  file?: string;
+  /** Override the source line, instead of using the one parsed from the trace. */
+  line?: number;
   locale?: string;
   runtime?: string;
   sections?: Section[];

tests/engine.test.ts

@@ -67,6 +67,25 @@ ValueError: invalid literal for int() with base 10: 'abc'`;
     expect(res).toBeNull();
   });
 
+  it("lets caller-provided file/line override the trace (e.g. Pyodide's <exec>)", () => {
+    const code = `for i in range(3)\n  print(i)`;
+    const raw = `Traceback (most recent call last):
+  File "/lib/python312.zip/_pyodide/_base.py", line 148, in _parse_and_compile_gen
+  File "<exec>", line 1
+    for i in range(3)
+                     ^
+SyntaxError: expected ':'`;
+
+    const without = friendlyExplain({ error: raw, code, runtime: "skulpt" });
+    expect(without!.trace.file).toBe("<exec>");
+
+    const withOverride = friendlyExplain({ error: raw, code, runtime: "skulpt", file: "main.py", line: 1 });
+    expect(withOverride!.trace.file).toBe("main.py");
+    expect(withOverride!.trace.line).toBe(1);
+    expect(withOverride!.trace.codeLine).toBe("for i in range(3)");
+    expect(withOverride!.summary).toContain("main.py");
+  });
+
   it("explains NameError with name and patch", () => {
     const code = `print("Hello")\nprint(kittens)\n`;
     const raw = `Traceback (most recent call last):