feat: simplify adapter usage - must be passed explicitly

The adapters now trust that they have been registered and passed a correct-looking error/trace, rather than using heuristics to guess whether the provided input is "Skulpt-like" or "Pyodide-like"

Author: grega

README.md

@@ -4,7 +4,7 @@ Todo:
 - Set up automated testing and publishing through GitHub Actions
 - Accessibility of output HTML
 
-A small, runtime-agnostic, library that explains Python error messages in a friendlier way, inspired by [p5.js's Friendly Error System](https://p5js.org/contribute/friendly_error_system/).
+A small, Pyodide and Skulpt-focused, library that explains Python error messages in a friendlier way, inspired by [p5.js's Friendly Error System](https://p5js.org/contribute/friendly_error_system/).
 
 It can be used in browser-based editors (like RPF's [Code Editor web component](https://github.com/RaspberryPiFoundation/editor-ui)) or any environment that executes Python code through Skulpt or Pyodide.
 
@@ -35,7 +35,8 @@ registerAdapter("pyodide", pyodideAdapter);
 // later, when you have an error string and some code:
 const result = friendlyExplain({
   error: rawTracebackString,
-  code: editorCode
+  code: editorCode,
+  runtime: "skulpt" // or "pyodide", matching the adapter/runtime that produced the traceback
 });
 
 // result.html is a ready-made snippet

docs/index.html

@@ -54,7 +54,7 @@ <h1>Python Friendly Error Messages - Demo</h1>
       : './vendor/python-friendly-error-messages/index.browser.js';
     const libPath = cacheBust ? `${libPathBase}?cb=${encodeURIComponent(cacheBust)}` : libPathBase;
 
-    const { friendlyExplain, loadCopydeck, registerAdapter, loadCopydeckFor, skulptAdapter, pyodideAdapter } = await import(libPath);
+    const { friendlyExplain, loadCopydeckFor, skulptAdapter, pyodideAdapter } = await import(libPath);
 
     async function initDemo() {
       const container = document.getElementById('demo-container');
@@ -92,13 +92,25 @@ <h1>Python Friendly Error Messages - Demo</h1>
 
       try {
         await loadCopydeckFor('en');
-        registerAdapter('skulpt', skulptAdapter);
-        registerAdapter('pyodide', pyodideAdapter);
+
+        const adaptersByRuntime = {
+          skulpt: skulptAdapter,
+          pyodide: pyodideAdapter
+        };
 
         const processedExamples = examples.map((example) => {
           try {
+            const runtimeAdapter = adaptersByRuntime[example.runtime];
+            if (!runtimeAdapter) {
+              throw new Error(`No adapter configured for runtime \"${example.runtime}\".`);
+            }
+            const parsedTrace = runtimeAdapter(example.trace, example.code);
+            if (!parsedTrace) {
+              throw new Error(`Could not parse trace for runtime \"${example.runtime}\".`);
+            }
+
             const result = friendlyExplain({
-              error: example.trace,
+              error: parsedTrace,
               code: example.code
             });
 

src/adapters/pyodide.ts

@@ -25,6 +25,18 @@ export const pyodideAdapter: AdapterFn = (raw, code) => {
   const q = (message || "").match(/["']([^"']+)["']/);
   if (q) name = q[1];
 
+  // Parse-quality gate:
+  // We only accept this adapter output if we recovered at least one structured
+  // signal that is useful for explanation selection or UI context:
+  // - type: error class from the final traceback line (for copydeck matching)
+  // - line: source location in user code (for codeLine/context extraction)
+  // - name: quoted symbol from the message (helpful for NameError/KeyError/etc.)
+  //
+  // If none are present, the input is not parseable enough for this adapter,
+  // so we return null and let the caller handle that failure explicitly.
+  const hasStructuredSignal = Boolean(type || line || name);
+  if (!hasStructuredSignal) return null;
+
   const t: Trace = {
     type,
     message,

src/adapters/skulpt.ts

@@ -8,9 +8,6 @@ const lastLineTypeMessage = (raw: string) => {
 };
 
 export const skulptAdapter: AdapterFn = (raw, code) => {
-  if (!/skulpt/i.test(raw) && !/Traceback/i.test(raw)) {
-    // still try; skulpt often includes "on line X of", etc.
-  }
   const { type, message, tail, lines } = lastLineTypeMessage(raw);
   let file: string | undefined, line: number | undefined, col: number | undefined;
 
@@ -33,6 +30,18 @@ export const skulptAdapter: AdapterFn = (raw, code) => {
   const q = (message || "").match(/["']([^"']+)["']/);
   if (q) name = q[1];
 
+  // Parse-quality gate:
+  // We only accept this adapter output if we recovered at least one structured
+  // signal that is useful for explanation selection or UI context:
+  // - type: error class from the final traceback line (for copydeck matching)
+  // - line: source location in user code (for codeLine/context extraction)
+  // - name: quoted symbol from the message (helpful for NameError/KeyError/etc.)
+  //
+  // If none are present, the input is not parseable enough for this adapter,
+  // so we return null and let the caller handle that failure explicitly.
+  const hasStructuredSignal = Boolean(type || line || name);
+  if (!hasStructuredSignal) return null;
+
   const t: Trace = {
     type,
     message,

src/engine.ts

@@ -17,28 +17,24 @@ const getUiString = (key: keyof NonNullable<CopyDeck["ui"]>, fallback: string):
 export const registerAdapter = (name: string, fn: (raw: string, code?: string) => Trace | null) =>
   (state.adapters[name] = fn);
 
-const coerceTrace = (input: string | Error | Trace, code?: string): Trace => {
+const coerceTrace = (input: string | Error | Trace, code?: string, runtime?: string): Trace => {
   if ((input as Trace).raw !== undefined) return input as Trace;
-  const raw = typeof input === "string" ? input : String((input as Error).stack || (input as Error).message || input);
-  // try adapters in registration order
-  for (const key of Object.keys(state.adapters)) {
-    const t = state.adapters[key](raw, code);
-    if (t) return t;
+
+  if (!runtime) {
+    throw new Error("Runtime is required when error is a string or Error. Pass opts.runtime or parse with an adapter first.");
   }
-  // generic fallback
-  const lines = raw.trim().split(/\r?\n/).filter(Boolean);
-  const tail = lines[lines.length - 1] || "";
-  const m = tail.match(/^(\w+Error)\s*:\s*(.*)$/);
-  const t: Trace = {
-    type: m ? m[1] : null,
-    message: m ? m[2] : tail,
-    raw,
-    runtime: "unknown"
-  };
-  if (code) {
-    t.codeLine = code.split(/\r?\n/)[(t.line || 1) - 1]?.trim();
+
+  const adapter = state.adapters[runtime];
+  if (!adapter) {
+    throw new Error(`No adapter registered for runtime \"${runtime}\".`);
+  }
+
+  const raw = typeof input === "string" ? input : String((input as Error).stack || (input as Error).message || input);
+  const parsed = adapter(raw, code);
+  if (!parsed) {
+    throw new Error(`Could not parse error for runtime \"${runtime}\".`);
   }
-  return t;
+  return parsed;
 };
 
 const pickVariant = (trace: Trace, code: string | undefined) => {
@@ -124,7 +120,7 @@ export const friendlyExplain = (opts: ExplainOptions): ExplainResult => {
   if (!state.copy) throw new Error("Copydeck not loaded");
   const code = opts.code;
 
-  const trace = coerceTrace(opts.error, code);
+  const trace = coerceTrace(opts.error, code, opts.runtime);
   if (code && trace.line && !trace.codeLine) {
     const lines = code.split(/\r?\n/);
     trace.codeLine = lines[trace.line - 1]?.trim();

src/types.ts

@@ -21,6 +21,7 @@ export type ExplainOptions = {
   error: string | Error | Trace;
   code?: string;
   locale?: string;
+  runtime?: string;
 };
 
 export type ExplainResult = {

tests/engine.test.ts

@@ -69,7 +69,7 @@ describe("engine", () => {
     const raw = `Traceback (most recent call last):
   File "main.py", line 2, in <module>
 NameError: name 'kittens' is not defined`;
-    const res = friendlyExplain({ error: raw, code });
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
     expect(res.trace.type).toBe("NameError");
     expect(res.title).toMatch(/name/i);
     expect(res.summary).toMatch(/kittens/);
@@ -82,7 +82,7 @@ NameError: name 'kittens' is not defined`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 1
 SyntaxError: invalid syntax`;
-    const res = friendlyExplain({ error: raw, code });
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
     expect(res.trace.type).toBe("SyntaxError");
     expect(res.title).toMatch(/colon/i);
     expect(res.patch).toMatch(/:\s*$/);
@@ -93,7 +93,7 @@ SyntaxError: invalid syntax`;
     const raw = `Traceback (most recent call last):
   File "main.py", line 2
 AttributeError: 'list' object has no attribute 'push'`;
-    const res = friendlyExplain({ error: raw, code });
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
     expect(res.trace.type).toBe("AttributeError");
     expect(res.patch).toContain(".append(");
   });

tests/loaders.test.ts

@@ -25,7 +25,10 @@ describe("loadCopydeckFor", () => {
     await loadCopydeckFor("en-GB");
     registerAdapter("skulpt", skulptAdapter);
 
-    const res = friendlyExplain({ error: "TypeError: bad", code: "" });
+    const res = friendlyExplain({
+      error: { type: "TypeError", message: "bad", raw: "TypeError: bad", runtime: "unknown" },
+      code: ""
+    });
     expect(res.title).toBe("Python error");
     expect((globalThis.fetch as any).mock.calls[0][0]).toMatch(/copydecks\/en-GB\/copydeck\.json/);
     expect((globalThis.fetch as any).mock.calls[1][0]).toMatch(/copydecks\/en\/copydeck\.json/);
@@ -41,7 +44,10 @@ describe("loadCopydeckFor", () => {
   it("still supports manual loadCopydeck for tests without fetch", () => {
     loadCopydeck(minimalDeck as any);
     registerAdapter("skulpt", skulptAdapter);
-    const res = friendlyExplain({ error: "NameError: name 'x' is not defined", code: "" });
+    const res = friendlyExplain({
+      error: { type: "NameError", message: "name 'x' is not defined", raw: "NameError: name 'x' is not defined", runtime: "unknown" },
+      code: ""
+    });
     expect(res.title).toBe("Python error");
   });
 });