feat: allow returning specific sections only in HTML

Author: grega

README.md

@@ -41,6 +41,14 @@ const result = friendlyExplain({
 
 // result.html is a ready-made snippet
 // or use result.title, result.summary, result.steps, result.patch, result.trace
+
+// optionally limit which sections appear in result.html:
+const result = friendlyExplain({
+  error: rawTracebackString,
+  code: editorCode,
+  runtime: "skulpt",
+  sections: ["title", "summary"] // "why", "steps", "patch", "details" also available
+});
 ```
 
 See the [demo](docs/README.md) for a full set of examples.

src/engine.ts

@@ -1,4 +1,4 @@
-import type { CopyDeck, ExplainOptions, ExplainResult, Trace } from "./types";
+import type { CopyDeck, ExplainOptions, ExplainResult, Section, Trace } from "./types";
 import { escapeHtml, safeRegexTest, tmpl } from "./utils";
 
 type InternalState = {
@@ -37,7 +37,7 @@ const coerceTrace = (input: string | Error | Trace, code?: string, runtime?: str
   return parsed;
 };
 
-const pickVariant = (trace: Trace, code: string | undefined) => {
+const pickVariant = (trace: Trace, code: string | undefined, sections?: Section[]) => {
   const deck = state.copy;
   const kind = trace.type && deck?.errors[trace.type] ? trace.type : "Other";
   const entry = deck?.errors[kind];
@@ -111,15 +111,16 @@ const pickVariant = (trace: Trace, code: string | undefined) => {
       patch = codeLine.replace(/\+\s*([A-Za-z_][A-Za-z0-9_]*)/, "+ str($1)");
     }
 
+    const has = (s: Section) => !sections || sections.includes(s);
     const html = [
-      `<div class="pfem__title">${titleHtml}</div>`,
-      `<div class="pfem__summary">${summaryHtml}</div>`,
-      whyHtml ? `<div class="pfem__why">${whyHtml}</div>` : "",
-      stepsHtml?.length ? `<ul class="pfem__steps">${stepsHtml.map((s) => `<li>${s}</li>`).join("")}</ul>` : "",
-      patch ? `<pre class="pfem__patch">${escapeHtml(patch)}</pre>` : "",
-      `<details class="pfem__details"><summary>${escapeHtml(getUiString("originalError", "Original error"))}</summary><pre>${escapeHtml(
+      has("title")   ? `<div class="pfem__title">${titleHtml}</div>` : "",
+      has("summary") ? `<div class="pfem__summary">${summaryHtml}</div>` : "",
+      has("why")     && whyHtml ? `<div class="pfem__why">${whyHtml}</div>` : "",
+      has("steps")   && stepsHtml?.length ? `<ul class="pfem__steps">${stepsHtml.map((s) => `<li>${s}</li>`).join("")}</ul>` : "",
+      has("patch")   && patch ? `<pre class="pfem__patch">${escapeHtml(patch)}</pre>` : "",
+      has("details") ? `<details class="pfem__details"><summary>${escapeHtml(getUiString("originalError", "Original error"))}</summary><pre>${escapeHtml(
         (trace.type || getUiString("error", "Error")) + ": " + trace.message
-      )}</pre></details>`
+      )}</pre></details>` : "",
     ].filter(Boolean).join("\n");
 
     return {
@@ -146,7 +147,7 @@ export const friendlyExplain = (opts: ExplainOptions): ExplainResult => {
     trace.codeLine = lines[trace.line - 1]?.trim();
   }
 
-  const chosen = pickVariant(trace, code);
+  const chosen = pickVariant(trace, code, opts.sections);
   if (!chosen) {
     return {
       trace,

src/types.ts

@@ -17,11 +17,14 @@ export type Trace = {
   version?: string;
 };
 
+export type Section = "title" | "summary" | "why" | "steps" | "patch" | "details";
+
 export type ExplainOptions = {
   error: string | Error | Trace;
   code?: string;
   locale?: string;
   runtime?: string;
+  sections?: Section[];
 };
 
 export type ExplainResult = {

tests/engine.test.ts

@@ -138,6 +138,19 @@ NameError: name 'kittens' is not defined`;
     expect(res.html).toContain('<span class="pfem__file">main.py</span>');
   });
 
+  it("sections option limits html output to specified sections", () => {
+    const code = `print("Hello")\nprint(kittens)\n`;
+    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, runtime: "skulpt", sections: ["title", "summary"] });
+    expect(res.html).toContain("pfem__title");
+    expect(res.html).toContain("pfem__summary");
+    expect(res.html).not.toContain("pfem__why");
+    expect(res.html).not.toContain("pfem__steps");
+    expect(res.html).not.toContain("pfem__details");
+  });
+
   it("escapes HTML in codeLine within html output", () => {
     const code = `for i in range(3)<script>alert(1)</script>\n  print(i)`;
     const raw = `Traceback (most recent call last):