@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/components/MachineDocs.tsx

@@ -1,5 +1,5 @@
 import { FileText } from "lucide-react";
-import { activeCatalogProfile } from "../data";
+import { activeCatalogDocs, activeCatalogProfile } from "../data";
 
 // The site as a language model reads it. The build (scripts/site-docs.mjs)
 // places the generated markdown under docs/ and llms.txt at the root, in the
@@ -10,11 +10,12 @@ import { activeCatalogProfile } from "../data";
 const base = import.meta.env.BASE_URL;
 
 const suffix = activeCatalogProfile.id === "portolan" ? "" : `${activeCatalogProfile.id}/`;
-const docs = `${base}docs/${suffix}`;
 const FILES = [
-  { href: suffix ? `${docs}llms.txt` : `${base}llms.txt`, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
-  { href: suffix ? `${docs}llms-full.txt` : `${base}llms-full.txt`, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
-  { href: docs, label: "docs/", title: "The generated markdown, page by page" },
+  ...(activeCatalogDocs ? [
+    { href: activeCatalogDocs.index, label: "llms.txt", title: "An index of every page, for a model that fetches on demand" },
+    { href: activeCatalogDocs.full, label: "llms-full.txt", title: "Every page in one file, for a model with a context window" },
+    { href: activeCatalogDocs.pages, label: "docs/", title: "The generated markdown, page by page" },
+  ] : []),
   { href: `${base}exports/mermaid/${suffix}`, label: "Mermaid", title: "Standalone sequence diagrams for every architecture flow" },
   ...(activeCatalogProfile.id === "example"
     ? [{ href: `${base}exports/backstage/catalog-info.yaml`, label: "Backstage", title: "Components, systems, APIs and resources for a Backstage catalog" }]

package/src/components/MethodRows.tsx

@@ -167,8 +167,15 @@ export function MethodRows({
                   className={method.deprecated ? "line-through" : undefined}
                 />
                 {method.http ? (
-                  <span className="chip mono" title="the route this operation answers on">
-                    {method.http.method} {method.http.path}
+                  <span
+                    className="chip mono"
+                    title={
+                      method.http.method
+                        ? "the route this operation answers on"
+                        : "the route this operation answers on; the HTTP verb is not declared in source"
+                    }
+                  >
+                    {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                   </span>
                 ) : null}
                 {method.soap ? (

package/src/components/PluginIcon.tsx

@@ -0,0 +1,77 @@
+// The mark beside a plugin's name: the brand's own where the plugin reads one
+// technology the reader knows by its logo, a lucide glyph where it reads a
+// format or a convention that has none. Both are drawn at the size and weight
+// of the lucide row they sit in, which is what TechIcon's opened viewBox is for.
+
+import {
+  BookOpen,
+  Cloud,
+  CodeXml,
+  Database,
+  FileCode2,
+  FileSignature,
+  FolderGit2,
+  GitFork,
+  Globe,
+  Inbox,
+  MessageSquare,
+  Package,
+  PenLine,
+  Route,
+  Share2,
+  ShieldCheck,
+  SpellCheck,
+  Terminal,
+  Users,
+  Waves,
+  Workflow,
+} from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+import type { PluginGlyph, PluginIconSpec } from "../lib/plugins";
+import { techGlyph } from "../lib/tech";
+import { TechIcon } from "./TechIcon";
+
+const GLYPHS: Record<PluginGlyph, LucideIcon> = {
+  code: CodeXml,
+  contract: FileSignature,
+  message: MessageSquare,
+  database: Database,
+  cloud: Cloud,
+  repository: FolderGit2,
+  pen: PenLine,
+  shield: ShieldCheck,
+  fork: GitFork,
+  share: Share2,
+  inbox: Inbox,
+  "file-code": FileCode2,
+  package: Package,
+  waves: Waves,
+  workflow: Workflow,
+  users: Users,
+  globe: Globe,
+  terminal: Terminal,
+  book: BookOpen,
+  "spell-check": SpellCheck,
+  route: Route,
+};
+
+export function PluginIcon({
+  icon,
+  size = 14,
+  className = "",
+}: {
+  icon: PluginIconSpec;
+  size?: number;
+  className?: string;
+}) {
+  if ("brand" in icon) {
+    const glyph = techGlyph(icon.brand);
+    // A brand the mark list does not carry is a mistake the test catches; at
+    // run time it falls back to the generic code glyph rather than to nothing.
+    if (glyph) return <TechIcon glyph={glyph} size={size} className={className} />;
+    return <CodeXml size={size} aria-hidden className={`block shrink-0 ${className}`} />;
+  }
+  const Glyph = GLYPHS[icon.lucide];
+  return <Glyph size={size} aria-hidden className={`block shrink-0 ${className}`} />;
+}

package/src/components/ProblemRow.tsx

@@ -1,13 +1,29 @@
-// One problem, as a row: what the near end is, where both ends live, and
-// the words for what is wrong with the edge between them. The problems page
-// lists every one of these; the overview shows the first few.
+// One problem, as a row: the edge, the words for what is wrong with it,
+// where it is met in the flows, and where the code is.
+//
+// The row is light on purpose: under a rule's heading on the Problems page
+// the rule's words are said once, above, and the row is the edge and its
+// note. On its own - the overview shows the first few - it wears the rule's
+// words too, as a link to the rule. The rule's subject says where the near
+// end leads: an event has a page, a table has a canvas, a channel, a call
+// and a deployment are shown on their service's page.
 
 import { Link } from "react-router";
+import { ExternalLink } from "lucide-react";
+import { catalog, index } from "../data";
 import type { Problem } from "../lib/derive";
 import { ctxStyle } from "../lib/context-color";
+import type { Kind } from "../lib/kinds";
 import { staggerStyle } from "../lib/motion";
+import { flowsOfProblem } from "../lib/problem-flows";
+import { useProblemRules } from "../lib/problem-rules";
+import type { RuleSubject } from "../lib/problem-rules";
+import { sourceHref } from "../lib/source-link";
 import {
+  aggregatePath,
   eventPath,
+  flowPath,
+  paths,
   servicePath,
   storePath,
   tablePath,
@@ -17,171 +33,175 @@ import { KindIcon } from "./kind";
 import { Ident } from "./Ident";
 
 /** The icon a problem row carries: what the near end of the edge IS. */
-const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
-  rpc: "service",
+export const ICON_OF: Record<RuleSubject, Kind> = {
+  service: "service",
+  call: "service",
+  copy: "service",
+  event: "event",
   consumer: "event",
-  "cross-service-fk": "table",
-  "cross-service-lineage": "table",
-  "shared-store": "table",
-  "persistence-drift": "table",
-  "column-type": "table",
-  "outbox-payload": "table",
-  "proto-missing": "service",
-  "proto-drift": "service",
-  "shared-channel": "event",
-  "channel-undeclared": "event",
-  "channel-unpublished": "service",
-  "message-encoding": "service",
-  "subscription-unresolved": "service",
+  channel: "event",
+  subscription: "service",
+  table: "table",
+  column: "table",
+  deployment: "service",
+  flow: "flow",
+  aggregate: "aggregate",
 };
 
-const KIND_NOTE: Record<Problem["kind"], string> = {
-  rpc: "the provider of this call is not in the catalog",
-  consumer: "this consumer of the event is not in the catalog",
-  "cross-service-fk": "foreign key across a service boundary",
-  "cross-service-lineage": "a value copied from another service's schema",
-  "shared-store": "a second service writes this database",
-  "persistence-drift": "this table no longer carries the aggregate it claims",
-  "column-type": "column type and domain type disagree",
-  "outbox-payload": "an outbox with no payload column",
-  "proto-missing":
-    "the provider is in the catalog but answers on no such method",
-  "proto-drift": "the vendored proto and provider schema disagree",
-  "shared-channel": "a second service publishes on this channel",
-  "channel-undeclared":
-    "this event goes out on a channel the service does not declare",
-  "channel-unpublished": "a declared channel no event of this service names",
-  "message-encoding": "publisher and subscriber use different payload encodings",
-  "subscription-unresolved":
-    "nothing in the catalog publishes what this service listens for",
-};
+/** A table or a view, whichever the id turns out to name. */
+function relationPath(id: string): string | null {
+  return tablePath(id) ?? viewPath(id);
+}
+
+/** A column's relation: its id minus the column, which is what the canvas can show. */
+function columnPath(id: string): string | null {
+  return relationPath(id.split(".").slice(0, -1).join("."));
+}
 
-/** Where the near end of a problem lives, by what kind of edge it is. */
-function nearPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "rpc":
-    // The near end is the CALLING service either way. `rpc` is a call whose
-    // peer is nobody; this is a call whose peer is known and whose method is
-    // not - and in both the thing to go and look at is the caller.
-    case "proto-missing":
-    case "proto-drift":
-      return servicePath(problem.service);
+/** Where the near end of a problem lives, by what the rule is about. */
+export function nearPath(over: RuleSubject, problem: Problem): string | null {
+  switch (over) {
+    case "event":
     case "consumer":
-    case "channel-undeclared":
       return eventPath(problem.id);
-    // The near end is an event when the service has one on the channel, and
-    // the service itself when the claim comes from its document alone.
-    case "shared-channel":
-      return eventPath(problem.id) ?? servicePath(problem.service);
-    case "channel-unpublished":
-    case "message-encoding":
-    case "subscription-unresolved":
-      return servicePath(problem.service);
-    case "shared-store":
-    case "persistence-drift":
-    case "outbox-payload":
-      return tablePath(problem.id);
-    // The id is "<relation>.<column>", so the relation is its own id minus the
-    // last segment — and the relation is what the canvas can actually show.
-    case "cross-service-fk":
-    case "column-type":
-      return relationPath(problem.id.split(".").slice(0, -1).join("."));
-    // Lineage is stated on a column, except when a view states it whole, so
-    // the id is one or the other and both are looked up the same way.
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.id) ??
-        relationPath(problem.id.split(".").slice(0, -1).join("."))
-      );
+    // A channel row is an event of the service when it has one on the
+    // address, and the service itself when the claim comes from its document.
+    case "channel":
+      return eventPath(problem.id) ?? (problem.service ? servicePath(problem.service) : null);
+    case "table":
+      return relationPath(problem.id);
+    case "column":
+      return columnPath(problem.id);
+    case "flow":
+      return flowPath(problem.id);
+    case "aggregate":
+      return aggregatePath(problem.id);
+    case "service":
+    case "call":
+    case "copy":
+    case "subscription":
+    case "deployment":
+      return problem.service ? servicePath(problem.service) : null;
   }
 }
 
-/** A table or a view, whichever the id turns out to name. */
-function relationPath(id: string): string | null {
-  return tablePath(id) ?? viewPath(id);
+/** Where the far end lives, when it is the id of something the catalog has. */
+function peerPath(peer: string): string | null {
+  if (!peer) return null;
+  return servicePath(peer) ?? eventPath(peer) ?? relationPath(peer) ?? columnPath(peer) ?? storePath(peer);
 }
 
-/** Where the far end lives, when the catalog knows it. */
-function peerPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "cross-service-fk":
-      return tablePath(problem.peer);
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.peer) ??
-        relationPath(problem.peer.split(".").slice(0, -1).join("."))
-      );
-    case "shared-store":
-    case "shared-channel":
-    case "message-encoding":
-      return servicePath(problem.peer);
-    case "outbox-payload":
-      return storePath(problem.peer);
-    default:
-      return null;
-  }
+/** An http(s) URL the note ends with, for a row whose far end is a page elsewhere - the deployer's. */
+function urlIn(note: string | undefined): string | null {
+  const match = note?.match(/https?:\/\/\S+$/);
+  return match ? match[0] : null;
 }
 
-export function ProblemRow({ problem, index }: { problem: Problem; index: number }) {
-  const near = nearPath(problem);
-  const peerTo = peerPath(problem);
-  const tone =
-    problem.severity === "error"
-      ? "var(--status-unresolved)"
-      : "var(--status-declared)";
+const MAX_FLOWS = 4;
+
+export function ProblemRow({
+  problem,
+  index: at,
+  showRule = true,
+}: {
+  problem: Problem;
+  index: number;
+  /** Say which rule made the row. Off under a heading that already says so. */
+  showRule?: boolean;
+}) {
+  const rules = useProblemRules();
+  const rule = rules.find((candidate) => candidate.id === problem.rule);
+  const over = rule?.over ?? "service";
+  const near = nearPath(over, problem);
+  const peerTo = peerPath(problem.peer);
+  const note = rule?.note ?? problem.rule;
+  const service = problem.service ? index.serviceById.get(problem.service) : undefined;
+  const source = problem.source ? sourceHref(problem.source, service) : null;
+  const url = over === "deployment" ? urlIn(problem.note) : null;
+  const text = url && problem.note ? problem.note.slice(0, problem.note.length - url.length).trim() : problem.note;
+  const flows = flowsOfProblem(catalog, index, over, problem);
+  const tone = problem.severity === "error" ? "text-unresolved" : "text-declared";
 
   return (
-    <div
-      className="stagger-in flex flex-wrap items-baseline gap-x-3 gap-y-1 rounded-control border px-3 py-2"
-      style={{ ...staggerStyle(index), borderColor: tone }}
-    >
-      <KindIcon kind={KIND_OF[problem.kind]} />
-      {near ? (
-        <Link
-          to={near}
-          data-nav-item
-          className="mono rounded-control text-accent hover:underline"
-          title={problem.id}
-        >
-          {problem.id}
-        </Link>
-      ) : (
-        <Ident value={problem.id} />
-      )}
-      <span aria-hidden className="text-muted">
-        →
-      </span>
-      {peerTo ? (
-        <Link
-          to={peerTo}
-          className="mono rounded-control hover:underline"
-          style={{ color: tone }}
-          title={problem.peer}
-        >
-          {problem.peer}
-        </Link>
-      ) : (
-        <Ident
-          value={problem.peer}
-          className={
-            problem.severity === "error" ? "text-unresolved" : "text-declared"
-          }
-          title={`${problem.peer} — ${KIND_NOTE[problem.kind]}. Click to copy.`}
-        />
-      )}
-      <span className="chip ctx" style={ctxStyle(problem.context)}>
-        <span aria-hidden className="dot" />
-        {problem.context}
-      </span>
-      <span className="mono ml-auto text-muted">{KIND_NOTE[problem.kind]}</span>
-      {problem.note ? (
-        <p className="w-full border-l-2 pl-2 border-line-strong text-muted">
-          {problem.note}
-        </p>
-      ) : null}
-      {problem.source ? (
-        <div className="mono w-full text-muted">
-          <Ident value={problem.source} />
+    <div className="stagger-in px-3 py-2.5" style={staggerStyle(at)} data-rule={problem.rule}>
+      <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+        <KindIcon kind={ICON_OF[over]} className="self-center" />
+        {near ? (
+          <Link to={near} data-nav-item className="mono rounded-control text-accent hover:underline" title={problem.id}>
+            {problem.id}
+          </Link>
+        ) : (
+          <Ident value={problem.id} />
+        )}
+        {/* A rule may name no far end; then there is no arrow to draw. */}
+        {problem.peer ? (
+          <>
+            <span aria-hidden className="text-faint">
+              →
+            </span>
+            {peerTo ? (
+              <Link to={peerTo} className={`mono rounded-control hover:underline ${tone}`} title={problem.peer}>
+                {problem.peer}
+              </Link>
+            ) : (
+              <Ident value={problem.peer} className={tone} title={`${problem.peer} — ${note}. Click to copy.`} />
+            )}
+          </>
+        ) : null}
+        {problem.context ? (
+          <span className="chip ctx" style={ctxStyle(problem.context)}>
+            <span aria-hidden className="dot" />
+            {problem.context}
+          </span>
+        ) : null}
+        {showRule ? (
+          <Link
+            to={`${paths.settingsRules()}#rule-${problem.rule}`}
+            className="mono ml-auto max-w-[45%] truncate rounded-control text-muted hover:text-ink hover:underline"
+            title={`rule ${problem.rule}${rule?.action ? ` — ${rule.action}` : ""}`}
+          >
+            {note}
+          </Link>
+        ) : null}
+      </div>
+      {text ? <p className="mt-1 max-w-prose text-muted">{text}</p> : null}
+      {flows.length > 0 || source || url ? (
+        <div className="mono mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1 text-muted">
+          {flows.length > 0 ? (
+            <span className="flex flex-wrap items-center gap-1">
+              <span className="text-faint">in</span>
+              {flows.slice(0, MAX_FLOWS).map((hit) => (
+                <Link
+                  key={hit.flow.id}
+                  to={hit.stepId ? paths.flowStep(hit.flow.slug, hit.stepId) : paths.flow(hit.flow.slug)}
+                  className="chip border-line-strong hover:border-accent hover:text-accent"
+                  title={hit.stepId ? `${hit.flow.name}, step ${hit.number}` : hit.flow.name}
+                >
+                  {hit.flow.name}
+                  {hit.number ? <span className="text-faint">·{hit.number}</span> : null}
+                </Link>
+              ))}
+              {flows.length > MAX_FLOWS ? (
+                <span className="text-faint" title={flows.slice(MAX_FLOWS).map((hit) => hit.flow.name).join(", ")}>
+                  +{flows.length - MAX_FLOWS}
+                </span>
+              ) : null}
+            </span>
+          ) : null}
+          {problem.source ? (
+            source ? (
+              <a href={source} target="_blank" rel="noreferrer" className="truncate rounded-control text-accent hover:underline" title={problem.source}>
+                {problem.source} ↗
+              </a>
+            ) : (
+              <Ident value={problem.source} className="truncate" />
+            )
+          ) : null}
+          {url ? (
+            <a href={url} target="_blank" rel="noreferrer" className="flex items-center gap-1 rounded-control text-accent hover:underline">
+              <ExternalLink size={12} aria-hidden /> open in the deployer
+            </a>
+          ) : null}
         </div>
       ) : null}
     </div>

package/src/components/RelationEvidence.test.tsx

@@ -0,0 +1,14 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { RelationEvidencePanel } from "./RelationEvidence";
+
+it("explains an ambiguous binding without choosing a candidate", () => {
+  const html = renderToStaticMarkup(<RelationEvidencePanel items={[
+    { kind: "binding", rule: "provider-signature", source: "di.go:12", symbol: "Build" },
+    { kind: "unresolved", rule: "ambiguous-binding", candidates: ["First", "Second"] },
+  ]} />);
+  for (const value of ["Why this relation exists", "inferred", "di.go:12", "Several implementations remain possible", "First", "Second"]) expect(html).toContain(value);
+});
+it("shows the absence of evidence explicitly", () => {
+  expect(renderToStaticMarkup(<RelationEvidencePanel items={[]} />)).toContain("No source evidence recorded");
+});

package/src/components/RelationEvidence.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { RelationEvidence } from "../catalog";
+
+const labels: Record<RelationEvidence["kind"], string> = {
+  "call-site": "Call site", function: "Function", binding: "Dependency binding",
+  contract: "Contract", resolution: "Catalog resolution", unresolved: "Unresolved",
+};
+const rules: Record<string, string> = {
+  "source-expression": "Expression in source",
+  "source-function": "Enclosing source function",
+  "provider-signature": "Provider signature (inferred)",
+  "store-port-convention": "Storage field, type or package name (inferred)",
+  "domain-port-convention": "Domain port mapped to the configured store (inferred)",
+  "ambiguous-binding": "Several implementations remain possible",
+  "generated-client-method": "Method declared by generated client",
+  "http-expression": "Outbound HTTP expression",
+  "analyzed-call-path": "Static analysis path; not a runtime trace",
+  "client-contract": "Client contract",
+  "catalog-contract": "Matching interface and method",
+  "event-declaration": "Declared event",
+  "repository-sql-call": "SQL operation inside repository",
+  "full-path": "Recovered full HTTP path",
+  "exact-route": "Exact HTTP route",
+  "unique-suffix": "Unique route suffix (heuristic)",
+  "continuation-entrypoint": "Matched continuation entrypoint",
+  "response-to-request": "Response associated with request",
+  "unresolved-target": "No unique target established",
+  "sql-alter-table": "ALTER TABLE in migration",
+  "sql-view-definition": "SQL view definition",
+  "sql-create-table": "CREATE TABLE in migration",
+  "domain-root-and-repository-layout": "Domain root and repository convention (inferred)",
+  "migration-aggregate-annotation": "Explicit aggregate annotation in migration",
+};
+
+/** One explanation surface for all flow kinds and schema relationships. */
+export function RelationEvidencePanel({ items, renderSource }: {
+  items: readonly RelationEvidence[];
+  renderSource?: (source: string) => ReactNode;
+}) {
+  return <section aria-label="Why this relation exists" className="my-3 rounded-card border border-line bg-surface p-3">
+    <h3 className="label mb-2">Why this relation exists</h3>
+    {items.length === 0 ? <p className="text-muted">No source evidence recorded in this fragment.</p> :
+      <ol className="space-y-3">
+        {items.map((item, i) => <li key={`${item.kind}-${i}`} className="min-w-0 border-l-2 border-line pl-3">
+          <div className={item.kind === "unresolved" ? "text-[var(--status-unresolved)]" : "text-ink"}>{labels[item.kind]}</div>
+          <div className="text-muted">{rules[item.rule] ?? item.rule}</div>
+          {item.symbol ? <div className="mono break-all">{item.symbol}</div> : null}
+          {item.source ? <div className="mono break-all text-muted">{renderSource ? renderSource(item.source) : item.source}</div> : null}
+          {item.candidates?.length ? <div className="mt-1"><span className="text-muted">Candidates</span><ul>{item.candidates.map((candidate) => <li className="mono break-all" key={candidate}>{candidate}</li>)}</ul></div> : null}
+        </li>)}
+      </ol>}
+  </section>;
+}

package/src/components/RuleMarks.tsx

@@ -0,0 +1,22 @@
+// What the source says a field's value must satisfy, as marks beside the
+// type: "required", "≥ 1 chars", "one of USD, EUR". One component so the
+// schema table, the field tree and the inline shape of a request say it the
+// same way; the words come from lib/rules.
+
+import type { Field } from "../catalog";
+import { ruleMarks } from "../lib/rules";
+
+export function RuleMarks({ field }: { field: Field }) {
+  const marks = ruleMarks(field);
+  if (marks.length === 0) return null;
+
+  return (
+    <>
+      {marks.map((mark) => (
+        <span key={mark.title} className="type-mark rule-mark" title={mark.title}>
+          {mark.text}
+        </span>
+      ))}
+    </>
+  );
+}

package/src/components/ShapeRows.tsx

@@ -10,6 +10,7 @@ import { Fragment, useState } from "react";
 import { ChevronDown, ChevronRight } from "lucide-react";
 import type { Field, RpcEnum } from "../catalog";
 import { parseType } from "../lib/shape";
+import { RuleMarks } from "./RuleMarks";
 
 /**
  * The enum a field's type names, among the ones the interface declares. By
@@ -91,26 +92,29 @@ export function ShapeRows({
                 primitive, so a reader can tell which names are worth following
                 without the row becoming a link it is not. */}
             <td className="mono py-0.5 pr-3 whitespace-nowrap text-muted">
-              {set ? (
-                <button
-                  type="button"
-                  onClick={() => toggle(field.name)}
-                  aria-expanded={shown}
-                  className="inline-flex items-center gap-1 rounded-control hover:text-ink"
-                  title={`${set.name}: ${set.values.length} values — click to ${shown ? "hide" : "show"} them`}
-                >
-                  {shown ? (
-                    <ChevronDown size={11} aria-hidden />
-                  ) : (
-                    <ChevronRight size={11} aria-hidden />
-                  )}
-                  {field.type}
-                </button>
-              ) : field.ref ? (
-                `${field.type} →`
-              ) : (
-                field.type
-              )}
+              <span className="inline-flex items-center gap-1.5">
+                {set ? (
+                  <button
+                    type="button"
+                    onClick={() => toggle(field.name)}
+                    aria-expanded={shown}
+                    className="inline-flex items-center gap-1 rounded-control hover:text-ink"
+                    title={`${set.name}: ${set.values.length} values — click to ${shown ? "hide" : "show"} them`}
+                  >
+                    {shown ? (
+                      <ChevronDown size={11} aria-hidden />
+                    ) : (
+                      <ChevronRight size={11} aria-hidden />
+                    )}
+                    {field.type}
+                  </button>
+                ) : field.ref ? (
+                  `${field.type} →`
+                ) : (
+                  field.type
+                )}
+                <RuleMarks field={field} />
+              </span>
             </td>
             <td className="py-0.5 text-muted">{field.doc}</td>
           </tr>