tablewalk 0.0.1

package/dist/client/schemaexport.js

@@ -0,0 +1,242 @@
+/**
+ * The schema, taken out of tablewalk.
+ *
+ * A diagram you can only look at inside the tool is a diagram that never
+ * reaches the design review, the pull request, or the person who asked what
+ * this database looks like. The whole point of drawing it is to be able to
+ * hand it to someone.
+ *
+ * Four formats, because they answer four different questions:
+ *
+ *   - **SVG** for the picture, at any size, still readable when someone zooms
+ *     into the corner of it.
+ *   - **PNG** for the places that will not take an SVG — a chat message, a
+ *     slide, an issue comment.
+ *   - **Mermaid** for a repository. GitHub renders it inline, so an ER diagram
+ *     in a README stays a diagram and, more importantly, diffs as text when
+ *     the schema changes.
+ *   - **Markdown** and **JSON** for reading and for feeding to something else.
+ *
+ * All of them export *what is selected*. The diagram's focus filter already
+ * narrows sixty-six tables to the eight someone cares about, and an export
+ * that ignored that would hand back the hairball they had just finished
+ * escaping.
+ */
+import { download } from './export.js';
+import { selection, toMarkdown, toMermaid, toSchemaJson } from './schematext.js';
+
+export { selection, toMarkdown, toMermaid, toSchemaJson };
+import { disclosure, el, state, toast } from './core.js';
+
+
+/* ---------- the picture ---------- */
+
+/* Properties worth carrying into a standalone file. Everything the diagram's
+   appearance depends on and nothing else — a full computed-style dump would
+   inline several hundred declarations per node and produce a file too large to
+   open. */
+const PAINTED = [
+  'fill-opacity', 'stroke-width', 'stroke-dasharray',
+  'font-family', 'font-size', 'font-weight', 'letter-spacing',
+  'opacity', 'text-anchor', 'text-transform',
+];
+
+/* Written even when the value is `none`, which the rest are not.
+   `fill: none` on an edge is not the absence of a fill — SVG's initial fill is
+   black, so dropping the declaration as a default turned every curve into a
+   solid black wedge and the diagram into an inkblot. */
+const ALWAYS = ['fill', 'stroke'];
+
+/**
+ * A copy of the drawing that stands on its own.
+ *
+ * The diagram on screen gets its colours from the page's stylesheet, so
+ * serialising the live SVG produces a file of black-on-transparent shapes —
+ * technically the same drawing and unrecognisable as it. Every painted
+ * property is read off the rendered element and written onto the clone, which
+ * is the only way to get a file that looks like what was on screen.
+ *
+ * The pan-and-zoom transform is dropped and the viewBox set to the drawing's
+ * own extent, so the export is the whole diagram rather than the part of it
+ * that happened to be in the window.
+ */
+export function standaloneSvg(svg, size) {
+  const clone = svg.cloneNode(true);
+  const from = svg.querySelectorAll('*');
+  const to = clone.querySelectorAll('*');
+
+  for (let i = 0; i < from.length; i += 1) {
+    const computed = getComputedStyle(from[i]);
+    const declarations = [...ALWAYS, ...PAINTED]
+      .map((property) => {
+        const value = computed.getPropertyValue(property);
+        if (!value) return '';
+        if (ALWAYS.includes(property)) return `${property}:${value}`;
+        return value !== 'none' && value !== 'normal' ? `${property}:${value}` : '';
+      })
+      .filter(Boolean)
+      .join(';');
+    if (declarations) to[i].setAttribute('style', declarations);
+  }
+
+  const content = clone.querySelector('g');
+  if (content) content.removeAttribute('transform');
+  clone.setAttribute('viewBox', `0 0 ${Math.ceil(size.width)} ${Math.ceil(size.height)}`);
+  clone.setAttribute('width', String(Math.ceil(size.width)));
+  clone.setAttribute('height', String(Math.ceil(size.height)));
+  clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  clone.style.removeProperty('width');
+  clone.style.removeProperty('height');
+
+  /* An explicit background. SVG has none, so a diagram exported from a light
+     page and opened on a dark one is invisible ink. */
+  const page = getComputedStyle(document.body).backgroundColor;
+  const backing = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+  backing.setAttribute('width', '100%');
+  backing.setAttribute('height', '100%');
+  backing.setAttribute('fill', page || '#ffffff');
+  clone.insertBefore(backing, clone.firstChild);
+
+  return new XMLSerializer().serializeToString(clone);
+}
+
+/**
+ * The same drawing, rasterised.
+ *
+ * At twice the size, because a PNG of a diagram is nearly always looked at on
+ * a display with more pixels than CSS says, and one rendered at 1× is the
+ * blurry screenshot this feature exists to replace.
+ */
+export async function svgToPng(markup, size, scale = 2) {
+  const blob = new Blob([markup], { type: 'image/svg+xml;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+  try {
+    const image = await new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error('The diagram could not be rendered as an image.'));
+      img.src = url;
+    });
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.ceil(size.width * scale);
+    canvas.height = Math.ceil(size.height * scale);
+    const context = canvas.getContext('2d');
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    return await new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/* ---------- saving ---------- */
+
+const stamp = () => new Date().toISOString().slice(0, 10);
+
+function base(schema, only) {
+  const slug = String(schema.label ?? 'schema').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  /* The filename says it is a subset. A file called `erp-schema.md` holding
+     eight of sixty-five tables misleads whoever opens it next week, and they
+     have no way to tell. */
+  const part = only?.size ? `-${only.size}-tables` : '';
+  return `${slug || 'schema'}${part}-${stamp()}`;
+}
+
+export async function exportSchema(kind, { schema = state.schema, only, svg, size } = {}) {
+  const name = base(schema, only);
+  switch (kind) {
+    case 'markdown':
+      download(`${name}.md`, toMarkdown(schema, only), 'text/markdown');
+      return;
+    case 'json':
+      download(`${name}.json`, toSchemaJson(schema, only), 'application/json');
+      return;
+    case 'mermaid':
+      download(`${name}.mmd`, toMermaid(schema, only), 'text/plain');
+      return;
+    case 'svg': {
+      if (!svg) throw new Error('There is no diagram to export.');
+      download(`${name}.svg`, standaloneSvg(svg, size), 'image/svg+xml');
+      return;
+    }
+    case 'png': {
+      if (!svg) throw new Error('There is no diagram to export.');
+      const blob = await svgToPng(standaloneSvg(svg, size), size);
+      const url = URL.createObjectURL(blob);
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = `${name}.png`;
+      link.click();
+      setTimeout(() => URL.revokeObjectURL(url), 0);
+      return;
+    }
+    default:
+      throw new Error(`Unknown export format: ${kind}`);
+  }
+}
+
+/* ---------- the control ---------- */
+
+/* Deliberately the same `<details class="export">` chrome the result-table
+   Export uses. Two menus that do the same kind of thing in the same product
+   should not have to be learned twice. */
+
+const FORMATS = [
+  ['svg', 'SVG', 'the drawing, any size'],
+  ['png', 'PNG', 'for chat and slides'],
+  ['mermaid', 'Mermaid', 'renders in a README'],
+  ['markdown', 'Markdown', 'columns and keys'],
+  ['json', 'JSON', 'the structured schema'],
+];
+
+/**
+ * Export the diagram.
+ *
+ * `picture()` is called at click time rather than captured, because the
+ * diagram is rebuilt on every focus change and a reference taken when the
+ * control was built would export the schema as it looked two edits ago.
+ */
+export function schemaExportControl({ schema = state.schema, only, picture } = {}) {
+  const menu = el('div', { class: 'export-menu' });
+  const wrap = disclosure(el('details', { class: 'export schema-export' }, [
+    el('summary', { class: 'export-summary', title: 'Export this schema' }, 'Export'),
+    menu,
+  ]));
+
+  const run = async (button, kind) => {
+    const was = button.textContent;
+    button.disabled = true;
+    button.textContent = 'Exporting…';
+    try {
+      await exportSchema(kind, { schema, only, ...(picture?.() ?? {}) });
+      wrap.open = false;
+      toast(`Exported ${only?.size ? `${only.size} tables` : 'the schema'} as ${kind.toUpperCase()}.`);
+    } catch (error) {
+      toast(error.message ?? 'The export failed.', 'error');
+    } finally {
+      button.disabled = false;
+      button.textContent = was;
+    }
+  };
+
+  /* Said once, at the top, rather than repeated on five buttons: whichever
+     format you pick, you get what is on screen. Someone who has narrowed
+     sixty-six tables to eight needs to know that before choosing, not after
+     opening the file. */
+  const scope = only?.size
+    ? `${only.size} table${only.size === 1 ? '' : 's'} — what the diagram is showing`
+    : `all ${schema.tables.length} tables`;
+  menu.append(el('p', { class: 'export-note export-scope', text: scope }));
+
+  for (const [kind, name, detail] of FORMATS) {
+    menu.append(el('button', {
+      type: 'button',
+      class: 'export-item',
+      onclick: (e) => void run(e.currentTarget, kind),
+    }, [
+      el('span', { class: 'export-kind', text: name }),
+      el('span', { class: 'export-count', text: detail }),
+    ]));
+  }
+
+  return wrap;
+}

package/dist/client/schematext.js

@@ -0,0 +1,125 @@
+/**
+ * The schema as text — Mermaid, Markdown, JSON — with no DOM and no state.
+ *
+ * Split from schemaexport.js so the server can speak these formats too:
+ * `tablewalk --export md` prints the same brief the browser downloads, and a
+ * committed CLAUDE.md schema section costs one command. Pure on purpose, the
+ * way shape.js is pure — a schema in, text out, importable from anywhere.
+ */
+
+/** The tables to export, and the keys wholly between them. */
+export function selection(schema, only) {
+  const wanted = only?.size
+    ? schema.tables.filter((t) => only.has(t.id))
+    : schema.tables;
+  const ids = new Set(wanted.map((t) => t.id));
+  /* Only keys with both ends in the selection. A reference to a table that is
+     not in the export is an edge pointing at nothing, which renders as a
+     dangling arrow and imports as a broken constraint. */
+  const keys = schema.foreignKeys.filter((fk) => ids.has(fk.from.table) && ids.has(fk.to.table));
+  return { tables: wanted, keys };
+}
+
+/* ---------- text formats ---------- */
+
+/**
+ * Mermaid `erDiagram`.
+ *
+ * Cardinality is stated as far as the catalog knows it, which is not very far:
+ * a foreign key says the child *may* point at one parent, and says nothing
+ * about whether a parent must have children. So every relationship is written
+ * `}o--||` — many-optional to exactly-one — which is what a nullable foreign
+ * key actually guarantees. Claiming more precision would be inventing it.
+ *
+ * Mermaid identifiers cannot contain a dot, so `app.invoice` becomes
+ * `app_invoice`. Said in a comment at the top of the output rather than
+ * silently, because someone comparing the diagram to their database will
+ * notice.
+ */
+export function toMermaid(schema, only) {
+  const { tables, keys } = selection(schema, only);
+  const safe = (id) => id.replace(/[^\w]/g, '_');
+  const lines = ['erDiagram'];
+
+  for (const table of tables) {
+    lines.push(`    ${safe(table.id)} {`);
+    for (const column of table.columns) {
+      const type = (column.type || 'unknown').replace(/[^\w]/g, '_') || 'unknown';
+      const marks = [column.primaryKey ? 'PK' : '', column.references ? 'FK' : '']
+        .filter(Boolean).join(',');
+      lines.push(`        ${type} ${column.name}${marks ? ` ${marks}` : ''}`);
+    }
+    lines.push('    }');
+  }
+
+  for (const fk of keys) {
+    const label = fk.from.columns.join(', ');
+    lines.push(`    ${safe(fk.to.table)} ||--o{ ${safe(fk.from.table)} : "${label}"`);
+  }
+
+  const renamed = tables.some((t) => safe(t.id) !== t.id);
+  return (renamed
+    ? '%% Names containing a dot are written with an underscore: Mermaid ids cannot hold one.\n'
+    : '') + lines.join('\n') + '\n';
+}
+
+/** A readable reference document, of the kind that belongs in a repository. */
+export function toMarkdown(schema, only) {
+  const { tables, keys } = selection(schema, only);
+  const out = [`# ${schema.label}`, ''];
+  out.push(
+    `${tables.length} table${tables.length === 1 ? '' : 's'}, `
+    + `${keys.length} foreign key${keys.length === 1 ? '' : 's'}.`,
+    '',
+  );
+
+  for (const table of tables) {
+    out.push(`## ${table.id}${table.isView ? ' *(view)*' : ''}`, '');
+    if (table.comment) out.push(table.comment, '');
+
+    out.push('| Column | Type | | References |', '| --- | --- | --- | --- |');
+    for (const c of table.columns) {
+      const marks = [
+        c.primaryKey ? '**key**' : '',
+        c.nullable ? '' : 'required',
+      ].filter(Boolean).join(', ');
+      const ref = c.references ? `→ \`${c.references.table}.${c.references.column}\`` : '';
+      out.push(`| \`${c.name}\` | ${c.type} | ${marks} | ${ref} |`);
+    }
+    out.push('');
+
+    /* What points *at* this table, which is the half a schema document
+       usually leaves out and the half tablewalk exists to show. */
+    const incoming = keys.filter((fk) => fk.to.table === table.id);
+    if (incoming.length) {
+      out.push('Referenced by:', '');
+      for (const fk of incoming) {
+        out.push(`- \`${fk.from.table}\` via \`${fk.from.columns.join(', ')}\``
+          + (fk.onDelete ? ` — on delete ${fk.onDelete}` : ''));
+      }
+      out.push('');
+    }
+  }
+  return out.join('\n');
+}
+
+/**
+ * The structured form.
+ *
+ * Deliberately the shape tablewalk itself uses rather than a format invented
+ * for export — anything that reads it is reading the same model the tool
+ * reasons about, and there is no second definition to keep in step.
+ */
+export function toSchemaJson(schema, only) {
+  const { tables, keys } = selection(schema, only);
+  return JSON.stringify({
+    label: schema.label,
+    dialect: schema.dialect,
+    readAt: schema.readAt,
+    exportedAt: new Date().toISOString(),
+    partial: Boolean(only?.size) && tables.length < schema.tables.length,
+    tables,
+    foreignKeys: keys,
+  }, null, 2);
+}
+

package/dist/client/shape.js

@@ -0,0 +1,178 @@
+/**
+ * What is in this database, answered from the catalog alone.
+ *
+ * The first minute with an unfamiliar schema is spent on questions the
+ * structure already answers: where does this thing centre, what are the tables
+ * I will actually query, how deep does it go, and what is that lump over there
+ * connected to nothing. The diagram shows all of it at once, which is a
+ * different thing from saying it — a picture of sixty-six tables answers "what
+ * is in here" only for someone who already knows.
+ *
+ * This is the non-model version of the feature the backlog files under LLM
+ * assistance, and it is the honest first version: everything below is derived
+ * from foreign keys that were introspected on connect, so it costs no network,
+ * no key, and cannot be wrong about a table it hallucinated.
+ *
+ * Pure on purpose — no DOM, no state, no imports. It takes a schema and returns
+ * a description, which is what makes it testable without a browser.
+ */
+
+/** A table has to be pointed at by this many others before it is a hub. */
+const HUB_MINIMUM = 2;
+
+/** How much of a table has to be foreign keys before it is a join table. */
+const JOIN_RATIO = 0.6;
+
+/**
+ * Describe a schema's shape.
+ *
+ * @param {{tables: Array, foreignKeys: Array}} schema
+ * @returns {{
+ *   counts: {tables: number, views: number, keys: number},
+ *   hubs: Array<{table: object, incoming: number, from: string[]}>,
+ *   leaves: object[],
+ *   joins: Array<{table: object, connects: string[]}>,
+ *   chain: object[],
+ *   islands: object[],
+ *   start: object | null,
+ * }}
+ */
+export function describeSchema(schema) {
+  const tables = schema?.tables ?? [];
+  const keys = (schema?.foreignKeys ?? []).filter((fk) => fk.from.table !== fk.to.table);
+  const byId = new Map(tables.map((t) => [t.id, t]));
+
+  /* Counted as *distinct tables*, not constraints. `work_order` pointing at
+     `employee` three times — raised_by, assigned_to, approved_by — says one
+     thing about the shape, not three, and counting constraints would rank a
+     table by how many roles one neighbour plays in it. */
+  const incoming = new Map(tables.map((t) => [t.id, new Set()]));
+  const outgoing = new Map(tables.map((t) => [t.id, new Set()]));
+  for (const fk of keys) {
+    incoming.get(fk.to.table)?.add(fk.from.table);
+    outgoing.get(fk.from.table)?.add(fk.to.table);
+  }
+
+  const inCount = (t) => incoming.get(t.id)?.size ?? 0;
+  const outCount = (t) => outgoing.get(t.id)?.size ?? 0;
+
+  const real = tables.filter((t) => !t.isView);
+
+  const hubs = real
+    .filter((t) => inCount(t) >= HUB_MINIMUM)
+    .sort((a, b) => inCount(b) - inCount(a) || a.name.localeCompare(b.name))
+    .slice(0, 4)
+    .map((table) => ({
+      table,
+      incoming: inCount(table),
+      from: [...(incoming.get(table.id) ?? [])].map((id) => byId.get(id)?.name ?? id).sort(),
+    }));
+
+  /* Leaves point outwards and are pointed at by nothing, which is what a
+     transaction or an event table looks like: the thing that happened, hanging
+     off the things it happened to. They are usually what someone actually
+     wants to query, and they are the least visible in a diagram because they
+     sit at the edges. */
+  const leaves = real
+    .filter((t) => outCount(t) > 0 && inCount(t) === 0)
+    .sort((a, b) => outCount(b) - outCount(a) || a.name.localeCompare(b.name));
+
+  /* A join table is mostly foreign keys, points at two or more things, and —
+     the part that separates it from a lookup table — is pointed at by almost
+     nothing itself. A join table *connects* things; things do not connect to
+     it.
+  
+     Without that last clause `country` qualifies: three of its five columns are
+     references, to currency, language and region. But half the schema points at
+     `country`, which makes it a dimension everyone shares rather than a bridge
+     between two tables, and calling it a join table would mislead about the
+     one thing this list exists to say. */
+  const joins = real
+    .filter((t) => {
+      const fkColumns = t.columns.filter((c) => c.references).length;
+      return outCount(t) >= 2 && inCount(t) <= 1 && t.columns.length > 0
+        && fkColumns / t.columns.length >= JOIN_RATIO;
+    })
+    .map((table) => ({
+      table,
+      connects: [...(outgoing.get(table.id) ?? [])].map((id) => byId.get(id)?.name ?? id).sort(),
+    }));
+
+  return {
+    counts: {
+      tables: real.length,
+      views: tables.length - real.length,
+      keys: schema?.foreignKeys?.length ?? 0,
+    },
+    hubs,
+    leaves,
+    joins,
+    chain: longestChain(tables, outgoing).map((id) => byId.get(id)).filter(Boolean),
+    islands: real.filter((t) => inCount(t) === 0 && outCount(t) === 0),
+    start: suggestStart(real, inCount, outCount),
+  };
+}
+
+/**
+ * The longest path of references, as the tables along it.
+ *
+ * The diagram computes the same *depth* to lay itself out, but a number is not
+ * the interesting part — "five levels deep" says less than "region → country →
+ * address → site → building → room", which is the shape of the domain written
+ * out. Recomputed here rather than shared because the diagram throws the path
+ * away and keeps only the count.
+ *
+ * A cycle is broken at the first table already on the path. A circular schema
+ * has no longest chain, and the alternative to stopping is not stopping.
+ */
+function longestChain(tables, outgoing) {
+  const best = new Map();
+
+  const walk = (id, seen) => {
+    if (seen.has(id)) return [];
+    if (best.has(id)) return best.get(id);
+
+    seen.add(id);
+    let longest = [];
+    for (const next of outgoing.get(id) ?? []) {
+      const path = walk(next, seen);
+      if (path.length > longest.length) longest = path;
+    }
+    seen.delete(id);
+
+    const result = [id, ...longest];
+    /* Only memoised when the walk was not truncated by the cycle guard — a
+       path cut short by `seen` is an answer about this route, not about this
+       table, and caching it would poison every later route through it. */
+    if (!longest.some((t) => seen.has(t))) best.set(id, result);
+    return result;
+  };
+
+  let chain = [];
+  for (const t of tables) {
+    const path = walk(t.id, new Set());
+    if (path.length > chain.length) chain = path;
+  }
+  return chain.length > 1 ? chain : [];
+}
+
+/**
+ * Where to start reading.
+ *
+ * The table that connects to the most, with a readable name to recognise rows
+ * by. Both halves matter: a join table is highly connected and tells you
+ * nothing on its own, and a lookup table is readable and leads nowhere.
+ */
+function suggestStart(tables, inCount, outCount) {
+  const scored = tables
+    .filter((t) => t.columns.some((c) => !c.primaryKey && !c.references))
+    .map((t) => ({
+      table: t,
+      // Outgoing weighted higher: a table you can walk *from* opens more of the
+      // schema than one that is merely popular.
+      score: outCount(t) * 2 + inCount(t),
+    }))
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score || a.table.name.localeCompare(b.table.name));
+  return scored[0]?.table ?? null;
+}

package/dist/client/shapecheck.js

@@ -0,0 +1,129 @@
+/**
+ * What this schema will cost you.
+ *
+ * The `lint` tool answers it for an agent and `--lint` answers it for CI, and
+ * the person actually looking at the database — the one who can *fix* the
+ * unindexed foreign key — had no way to ask. Every finding is a fact this
+ * tool already has on screen somewhere: the keys are in the diagram, the
+ * types are in the table view. What the check adds is the consequence, which
+ * is the part nobody reads a catalog to work out.
+ *
+ * It runs the same tool through the same endpoint an agent uses, for the same
+ * reason the value search does: two implementations of "what is wrong with
+ * this shape" would eventually disagree, and then one of them is lying.
+ */
+import { api, el, findTable, go, tableView, trapFocus } from './core.js';
+
+let panel = null;
+/** Undoes the focus trap, and hands the keyboard back where it came from. */
+let release = null;
+
+const TONE = { high: 'high', medium: 'medium', low: 'low' };
+
+export function openShapeCheck() {
+  if (panel) return;
+  panel = el('div', {
+    class: 'conn-manager shape-check',
+    role: 'dialog',
+    'aria-modal': 'true',
+    'aria-label': 'Check the shape',
+  });
+  document.body.append(panel);
+  release = trapFocus(panel);
+  document.addEventListener('keydown', onKey, true);
+  panel.replaceChildren(el('div', { class: 'conn-inner' }, [
+    el('p', { class: 'loading', text: 'Reading the catalog…' }),
+  ]));
+  void run();
+}
+
+/** Findings of one table, gathered under the rule they share. */
+function byRule(list) {
+  const groups = new Map();
+  for (const finding of list) {
+    const found = groups.get(finding.rule) ?? [];
+    found.push(finding);
+    groups.set(finding.rule, found);
+  }
+  return [...groups];
+}
+
+function close() {
+  release?.();
+  release = null;
+  panel?.remove();
+  panel = null;
+  document.removeEventListener('keydown', onKey, true);
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape' || !panel) return;
+  e.preventDefault();
+  close();
+}
+
+async function run() {
+  let answer;
+  try {
+    /* `all: true` because this is the panel, not an agent's first orientation.
+       The tool samples five findings per rule by default — right when the
+       reader is an agent spending context to find out what kind of trouble a
+       schema is in, wrong when it is a person who opened a list to read it. */
+    answer = await api('/api/agent/call', { name: 'lint', arguments: { all: true } });
+  } catch (err) {
+    if (panel) panel.replaceChildren(el('div', { class: 'conn-inner' }, el('p', { class: 'note', text: err.message })));
+    return;
+  }
+  if (!panel) return;
+  const result = answer.structuredContent ?? {};
+  const findings = result.findings ?? [];
+  /* What a rule costs is sent once now, keyed by rule, rather than repeated on
+     every finding — which is what this panel was already doing with it. */
+  const rules = result.rules ?? {};
+  const counts = result.counts ?? { high: 0, medium: 0, low: 0 };
+
+  const byTable = new Map();
+  for (const finding of findings) {
+    const list = byTable.get(finding.table) ?? [];
+    list.push(finding);
+    byTable.set(finding.table, list);
+  }
+
+  panel.replaceChildren(el('div', { class: 'conn-inner' }, [
+    el('div', { class: 'conn-head' }, [
+      el('h2', { text: 'Check the shape' }),
+      el('button', { type: 'button', class: 'ghost', text: '×', 'aria-label': 'Close', onclick: close }),
+    ]),
+    el('p', { class: 'find-note' }, [
+      findings.length
+        ? el('span', { text: `${counts.high} high, ${counts.medium} medium, ${counts.low} low — read from the catalog alone: no queries, no guesses about intent.` })
+        : el('span', { text: 'Nothing to report: no missing keys, unindexed references or naive timestamps.' }),
+    ]),
+    ...[...byTable].map(([table, list]) => el('div', { class: 'shape-check-group' }, [
+      el('button', {
+        type: 'button',
+        class: 'shape-check-table',
+        title: `Open ${table}`,
+        /* Every finding is about a table, and the useful next move is
+           looking at it — so the heading is the way there rather than a
+           label beside a link. */
+        onclick: () => { close(); go(tableView(findTable(table)?.id ?? table), 'reset'); },
+      }, [
+        el('span', { text: findTable(table)?.name ?? table }),
+        el('span', { class: 'shape-check-count', text: `${list.length}` }),
+      ]),
+      /* Grouped by rule, with the cost said once. Four findings of the same
+         rule are four different columns and one consequence, and printing
+         the consequence four times is how a list stops being read. */
+      ...byRule(list).map(([rule, found]) => el('div', {
+        class: `shape-check-rule-group tone-${TONE[found[0].severity] ?? 'low'}`,
+      }, [
+        el('p', { class: 'shape-check-why' }, [
+          el('span', { class: 'shape-check-rule', text: rule }),
+          el('span', { text: rules[rule]?.why ?? found[0].why ?? '' }),
+        ]),
+        ...found.map((finding) => el('p', { class: 'shape-check-item', text: finding.message })),
+      ])),
+    ])),
+  ]));
+}