feat(frontend): SQL/CTE viewer with shiki highlighting

TDD: SqlViewer renders collapsible CTE blocks with name/field-count/
test-status badges, shiki-highlighted SQL body (dangerouslySetInnerHTML),
per-field comments, and a vertical/horizontal layout toggle.
highlight.ts wraps shiki as a lazy singleton; tests mock it for
determinism (pattern mirrors mermaid.ts).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

frontend/package-lock.json

@@ -18,6 +18,7 @@
         "react-dom": "^18.3.1",
         "react-markdown": "^10.1.0",
         "remark-gfm": "^4.0.1",
+        "shiki": "^4.3.0",
         "sonner": "^2.0.7",
         "tailwind-merge": "^3.6.0",
         "tw-animate-css": "^1.4.0",
@@ -2149,6 +2150,106 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@shikijs/core": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.3.0.tgz",
+      "integrity": "sha512-EooU3i9F6IAE8kEu+AnGf9DFZWkQBZ+hJn3tLVbsH+61mtQiva5biai66fAA6nvFPXkLgvrh7BrR7YcJU83xQQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/primitive": "4.3.0",
+        "@shikijs/types": "4.3.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4",
+        "hast-util-to-html": "^9.0.5"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/engine-javascript": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-4.3.0.tgz",
+      "integrity": "sha512-hTv/KiFf2tpiqlACPiztGGurEARWIutB8YUhcrA1pUC7VzzwKO+g5crUocrLztrZ5ro5Z4hbXg7bYclETn3gSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.3.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "oniguruma-to-es": "^4.3.6"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/engine-oniguruma": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-4.3.0.tgz",
+      "integrity": "sha512-1vMdN3gHfnKfLYwecUI2ITJI4RhHt96xEaJumVn7Heb0IlJ8WQMIH0Voak+2j22BpSNKdnOfB/pCTPnPm2gq7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.3.0",
+        "@shikijs/vscode-textmate": "^10.0.2"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/langs": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-4.3.0.tgz",
+      "integrity": "sha512-rnlqFbBRSys9bT4gl/5rw9RnS0W/I84ZldXPkO7cvlEMoV85TyF/aU01N7/NbSR776RNLjrJKjfFUXJR6wN1Cg==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.3.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/primitive": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/primitive/-/primitive-4.3.0.tgz",
+      "integrity": "sha512-CPkz64PTa5diRW1ggzMZH9VM/du4RNChYgVtgqrFcgruvIybmCvySv8GkiHSczUHXYuuR8TdKEwFx+UnZMpgdg==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.3.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/themes": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-4.3.0.tgz",
+      "integrity": "sha512-Avgt05YiT+Y3prjIc9lmQxhJzHBcCfR6cjiFW4OyaMBbt2A6trX5rfjUzx+Vj/mE9qpArYjatnqo9XPjQNW/AQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.3.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/types": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-4.3.0.tgz",
+      "integrity": "sha512-oc8b9U2SYvofKZk8e/737nIX0qwf6eV2vHFATeObAu7r+mUVpLs8Re0BmVkIjAWAYgkmG/CzLNo7rzuBzRu/wQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/vscode-textmate": {
+      "version": "10.0.2",
+      "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz",
+      "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==",
+      "license": "MIT"
+    },
     "node_modules/@sindresorhus/merge-streams": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz",
@@ -5544,6 +5645,29 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/hast-util-to-html": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
+      "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "html-void-elements": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "stringify-entities": "^4.0.0",
+        "zwitch": "^2.0.4"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-to-jsx-runtime": {
       "version": "2.3.6",
       "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
@@ -5628,6 +5752,16 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/html-void-elements": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz",
+      "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
@@ -7739,6 +7873,23 @@
         "node": ">=6"
       }
     },
+    "node_modules/oniguruma-parser": {
+      "version": "0.12.2",
+      "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.2.tgz",
+      "integrity": "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==",
+      "license": "MIT"
+    },
+    "node_modules/oniguruma-to-es": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.6.tgz",
+      "integrity": "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==",
+      "license": "MIT",
+      "dependencies": {
+        "oniguruma-parser": "^0.12.2",
+        "regex": "^6.1.0",
+        "regex-recursion": "^6.0.2"
+      }
+    },
     "node_modules/open": {
       "version": "11.0.0",
       "resolved": "https://registry.npmjs.org/open/-/open-11.0.0.tgz",
@@ -8601,6 +8752,30 @@
         "node": ">=8"
       }
     },
+    "node_modules/regex": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz",
+      "integrity": "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-recursion": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz",
+      "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-utilities": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz",
+      "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==",
+      "license": "MIT"
+    },
     "node_modules/remark-gfm": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
@@ -9137,6 +9312,25 @@
         "node": ">=8"
       }
     },
+    "node_modules/shiki": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-4.3.0.tgz",
+      "integrity": "sha512-NKKjWzR6LIGL3sXBrWDw9sDS9cxx42/DkysaNqJEeOWE8Kix5gpak0bc00OfDVEO4oyXSyz8+aRaqKoBD1yo7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/core": "4.3.0",
+        "@shikijs/engine-javascript": "4.3.0",
+        "@shikijs/engine-oniguruma": "4.3.0",
+        "@shikijs/langs": "4.3.0",
+        "@shikijs/themes": "4.3.0",
+        "@shikijs/types": "4.3.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/side-channel": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz",

frontend/package.json

@@ -23,6 +23,7 @@
     "react-dom": "^18.3.1",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
+    "shiki": "^4.3.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.6.0",
     "tw-animate-css": "^1.4.0",

frontend/src/viewers/SqlViewer.test.tsx

@@ -0,0 +1,75 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SqlViewer } from "./SqlViewer";
+
+vi.mock("./highlight", () => ({
+  highlightSql: vi.fn().mockResolvedValue('<pre data-testid="hl">SELECT 1</pre>'),
+}));
+
+const blocks = [
+  {
+    name: "base_orders",
+    fields: 5,
+    testStatus: "passed" as const,
+    sql: "SELECT id, amount FROM orders",
+    comments: { amount: "importo lordo" },
+  },
+  {
+    name: "final_query",
+    fields: 3,
+    testStatus: "failed" as const,
+    sql: "SELECT * FROM base_orders",
+  },
+];
+
+test("(a) renders headers with name, field count, and test-status badge", async () => {
+  render(<SqlViewer blocks={blocks} />);
+  // Headers should be visible immediately
+  expect(screen.getByText("base_orders")).toBeInTheDocument();
+  expect(screen.getByText("final_query")).toBeInTheDocument();
+
+  // Field counts
+  expect(screen.getByText(/5 campi/i)).toBeInTheDocument();
+  expect(screen.getByText(/3 campi/i)).toBeInTheDocument();
+
+  // Test-status badges
+  expect(screen.getByText(/passed/i)).toBeInTheDocument();
+  expect(screen.getByText(/failed/i)).toBeInTheDocument();
+});
+
+test("(b) bodies start expanded and clicking header collapses then re-expands", async () => {
+  const user = userEvent.setup();
+  render(<SqlViewer blocks={blocks} />);
+
+  // Both highlighted bodies should appear after async highlight resolves
+  await waitFor(() => {
+    expect(screen.getAllByTestId("hl")).toHaveLength(2);
+  });
+
+  // Collapse the first block by clicking its header
+  const firstHeader = screen.getByRole("button", { name: /base_orders/i });
+  await user.click(firstHeader);
+
+  // Now only one highlighted block visible
+  await waitFor(() => {
+    expect(screen.getAllByTestId("hl")).toHaveLength(1);
+  });
+
+  // Re-expand
+  await user.click(firstHeader);
+  await waitFor(() => {
+    expect(screen.getAllByTestId("hl")).toHaveLength(2);
+  });
+});
+
+test("(c) layout toggle switches between vertical and horizontal", async () => {
+  render(<SqlViewer blocks={blocks} />);
+
+  const toggle = screen.getByRole("button", { name: /orizzontale|verticale/i });
+  expect(toggle).toBeInTheDocument();
+  await userEvent.click(toggle);
+  // After click the label should flip
+  expect(
+    screen.getByRole("button", { name: /orizzontale|verticale/i })
+  ).toBeInTheDocument();
+});

frontend/src/viewers/SqlViewer.tsx

@@ -0,0 +1,126 @@
+import React, { useEffect, useState } from "react";
+import { highlightSql } from "./highlight";
+
+export interface SqlBlock {
+  name: string;
+  fields?: number;
+  testStatus?: "passed" | "failed" | "untested";
+  sql: string;
+  comments?: Record<string, string>;
+}
+
+type Layout = "vertical" | "horizontal";
+
+const STATUS_LABELS: Record<string, string> = {
+  passed: "passed",
+  failed: "failed",
+  untested: "untested",
+};
+
+const STATUS_CLASSES: Record<string, string> = {
+  passed: "bg-green-100 text-green-800",
+  failed: "bg-red-100 text-red-800",
+  untested: "bg-gray-100 text-gray-600",
+};
+
+function Block({ block }: { block: SqlBlock }) {
+  const [open, setOpen] = useState(true);
+  const [html, setHtml] = useState<string>("");
+
+  useEffect(() => {
+    let cancelled = false;
+    highlightSql(block.sql).then((result) => {
+      if (!cancelled) setHtml(result);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [block.sql]);
+
+  const badge = block.testStatus ? STATUS_LABELS[block.testStatus] : null;
+  const badgeClass = block.testStatus
+    ? STATUS_CLASSES[block.testStatus]
+    : "";
+
+  return (
+    <div className="sql-block border rounded mb-2">
+      <button
+        className="w-full flex items-center gap-2 px-3 py-2 text-left font-mono text-sm hover:bg-muted/30"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+      >
+        <span className="select-none">{open ? "▾" : "▸"}</span>
+        <span className="font-semibold">{block.name}</span>
+        {block.fields !== undefined && (
+          <span className="text-muted-foreground text-xs">
+            {block.fields} campi
+          </span>
+        )}
+        {badge && (
+          <span
+            className={`ml-auto text-xs px-1.5 py-0.5 rounded ${badgeClass}`}
+          >
+            {badge}
+          </span>
+        )}
+      </button>
+
+      {open && (
+        <div className="sql-block-body px-3 pb-3">
+          {html ? (
+            // eslint-disable-next-line react/no-danger
+            <div dangerouslySetInnerHTML={{ __html: html }} />
+          ) : (
+            <pre className="text-sm opacity-50">{block.sql}</pre>
+          )}
+          {block.comments && Object.keys(block.comments).length > 0 && (
+            <dl className="mt-2 text-xs text-muted-foreground grid grid-cols-[auto_1fr] gap-x-2 gap-y-0.5">
+              {Object.entries(block.comments).map(([field, comment]) => (
+                <React.Fragment key={field}>
+                  <dt className="font-mono font-medium">{field}</dt>
+                  <dd>{comment}</dd>
+                </React.Fragment>
+              ))}
+            </dl>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function SqlViewer({ blocks }: { blocks: SqlBlock[] }) {
+  const [layout, setLayout] = useState<Layout>("vertical");
+
+  return (
+    <div className="sql-viewer">
+      <div className="flex gap-2 mb-2">
+        <button
+          className="text-xs px-2 py-1 border rounded hover:bg-muted/30"
+          onClick={() =>
+            setLayout((l) => (l === "vertical" ? "horizontal" : "vertical"))
+          }
+        >
+          {layout === "vertical" ? "Orizzontale" : "Verticale"}
+        </button>
+      </div>
+
+      <div
+        className={
+          layout === "horizontal"
+            ? "flex gap-2 overflow-x-auto"
+            : "flex flex-col"
+        }
+      >
+        {blocks.map((block) => (
+          <div
+            key={block.name}
+            className={layout === "horizontal" ? "min-w-72 flex-1" : ""}
+          >
+            <Block block={block} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

frontend/src/viewers/highlight.ts

@@ -0,0 +1,21 @@
+import type { Highlighter } from "shiki";
+
+let _highlighter: Highlighter | null = null;
+
+async function getHighlighter(): Promise<Highlighter> {
+  if (_highlighter) return _highlighter;
+  const { createHighlighter } = await import("shiki");
+  _highlighter = await createHighlighter({
+    themes: ["github-light", "github-dark"],
+    langs: ["sql"],
+  });
+  return _highlighter;
+}
+
+export async function highlightSql(code: string): Promise<string> {
+  const hl = await getHighlighter();
+  return hl.codeToHtml(code, {
+    lang: "sql",
+    themes: { light: "github-light", dark: "github-dark" },
+  });
+}