@shortlink-org/portolan 0.2.3 → 0.2.4

package/src/catalog.test.ts

@@ -105,7 +105,7 @@ describe("validateCatalog", () => {
     if (!step) throw new Error("fixture has no steps");
     step.ref = "shop.oms.order.NoSuchEvent";
     expect(() => validateCatalog(bad)).toThrowError(
-      /resolves to neither an Event nor an RpcCall/,
+      /resolves to neither an Event, an RpcCall nor a method/,
     );
     step.status = "unresolved";
     expect(() => validateCatalog(bad)).not.toThrow();
@@ -1077,7 +1077,10 @@ describe("validateCatalog: channels", () => {
   }
 
   it("accepts a service that declares what it says on the bus", () => {
-    expect(() => validateCatalog(speaking())).not.toThrow();
+    const good = speaking();
+    good.contexts[0]!.services[0]!.channels![0]!.messages[0]!.encoding = "msgpack";
+    good.contexts[0]!.services[0]!.channels![0]!.messages[0]!.contentType = "application/msgpack";
+    expect(() => validateCatalog(good)).not.toThrow();
   });
 
   // A service with no document is the normal case, and it is not a service
@@ -1130,6 +1133,14 @@ describe("validateCatalog: channels", () => {
 
     expect(() => validateCatalog(bad)).toThrow(/neither send nor receive/);
   });
+
+  it("rejects an explicitly empty message encoding", () => {
+    const bad = speaking();
+    const message = bad.contexts[0]!.services[0]!.channels![0]!.messages[0]!;
+    message.encoding = "";
+
+    expect(() => validateCatalog(bad)).toThrow(/empty encoding/);
+  });
 });
 
 // A system outside the estate with a contract sits at the root beside the

package/src/components/ChannelRows.messagepack.test.tsx

@@ -0,0 +1,28 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { MemoryRouter } from "react-router";
+import { describe, expect, it } from "vitest";
+import type { Channel } from "../catalog";
+import { ChannelRows } from "./ChannelRows";
+
+describe("ChannelRows MessagePack presentation", () => {
+  it("shows a machine-readable encoding with its declared content type", () => {
+    const channel: Channel = {
+      address: "inventory.snapshots",
+      kind: "message",
+      messages: [{
+        name: "inventory.Snapshot",
+        direction: "send",
+        encoding: "msgpack",
+        contentType: "application/msgpack",
+      }],
+    };
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRows channels={[channel]} service="shop.inventory" />
+      </MemoryRouter>,
+    );
+
+    expect(markup).toContain('title="application/msgpack"');
+    expect(markup).toContain(">msgpack</span>");
+  });
+});

package/src/components/ChannelRows.test.tsx

@@ -0,0 +1,54 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { MemoryRouter } from "react-router";
+import { describe, expect, it } from "vitest";
+import type { Channel } from "../catalog";
+import { ChannelRowsContent } from "./ChannelRows";
+
+const kafka: Channel = {
+  address: "orders/created",
+  kind: "message",
+  title: "Kafka · orders/created",
+  messages: [],
+};
+
+const nats: Channel = {
+  address: "orders.created",
+  kind: "message",
+  title: "JetStream subject",
+  messages: [],
+};
+
+describe("ChannelRows Kafka UI integration", () => {
+  it("links only Kafka cards to their exact topic when configured", () => {
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent
+          channels={[kafka, nats]}
+          service="shop.orders"
+          kafkaUi="https://ops.example/ui/clusters/prod"
+        />
+      </MemoryRouter>,
+    );
+
+    expect(markup).toContain("view in Kafka UI");
+    expect(markup).toContain(
+      'href="https://ops.example/ui/clusters/prod/all-topics/orders%2Fcreated"',
+    );
+    expect(markup.match(/view in Kafka UI/g)).toHaveLength(1);
+  });
+
+  it("does not offer an operational link before Kafka UI is configured", () => {
+    const markup = renderToStaticMarkup(
+      <MemoryRouter>
+        <ChannelRowsContent
+          channels={[kafka]}
+          service="shop.orders"
+          kafkaUi=""
+        />
+      </MemoryRouter>,
+    );
+
+    expect(markup).not.toContain("view in Kafka UI");
+  });
+
+});

package/src/components/ChannelRows.tsx

@@ -13,13 +13,22 @@
 // Problems page says which; a row that quietly dropped it would be the site
 // hiding the interesting case.
 
+import { ExternalLink } from "lucide-react";
 import { Link } from "react-router";
 import type { Channel, ChannelMessage } from "../catalog";
-import { index } from "../data";
+import { catalog, index } from "../data";
+import {
+  isKafkaChannel,
+  kafkaHandoffChannels,
+  kafkaUiTopicUrl,
+  useKafkaUi,
+} from "../lib/kafka-ui";
 import { eventPath } from "../routes";
 import { Ident } from "./Ident";
 import { RowActions } from "./RowActions";
 
+const KAFKA_HANDOFF_CHANNELS = kafkaHandoffChannels(catalog);
+
 /** The event that goes out under a wire name, when the catalog knows one. */
 function publisherOf(name: string) {
   const event = index.eventByWireName.get(name);
@@ -75,6 +84,11 @@ function MessageRow({
               {elsewhere}
             </span>
           ) : null}
+          {message.encoding || message.contentType ? (
+            <span className="chip mono" title={message.contentType || "payload encoding"}>
+              {message.encoding || message.contentType}
+            </span>
+          ) : null}
         </div>
         {message.title || message.doc ? (
           <p className="mt-0.5 text-muted">{message.doc || message.title}</p>
@@ -91,20 +105,53 @@ export function ChannelRows({
 }: {
   channels: Channel[];
   service: string;
+}) {
+  const kafkaUi = useKafkaUi((state) => state.url);
+  return (
+    <ChannelRowsContent
+      channels={channels}
+      service={service}
+      kafkaUi={kafkaUi}
+    />
+  );
+}
+
+/** The presentational half is exported so the generated links can be rendered in isolation. */
+export function ChannelRowsContent({
+  channels,
+  service,
+  kafkaUi,
+}: {
+  channels: Channel[];
+  service: string;
+  kafkaUi: string;
 }) {
   return (
     <div className="flex flex-col gap-section" data-nav-list>
       {channels.map((channel) => (
         <div key={channel.address} className="rounded-card border border-line">
-          <div className="flex flex-wrap items-baseline gap-x-2 border-b border-line px-3 py-2">
-            <Ident value={channel.address} />
-            {channel.kind === "job" ? (
-              <span className="chip">work queue</span>
-            ) : channel.kind === "message" ? (
-              <span className="chip">message stream</span>
-            ) : null}
-            {channel.title ? (
-              <span className="text-muted">{channel.title}</span>
+          <div className="flex flex-wrap items-center gap-x-3 gap-y-2 border-b border-line px-3 py-2">
+            <div className="flex min-w-0 flex-1 flex-wrap items-baseline gap-x-2">
+              <Ident value={channel.address} />
+              {channel.kind === "job" ? (
+                <span className="chip">work queue</span>
+              ) : channel.kind === "message" ? (
+                <span className="chip">message stream</span>
+              ) : null}
+              {channel.title ? (
+                <span className="text-muted">{channel.title}</span>
+              ) : null}
+            </div>
+            {kafkaUi && isKafkaChannel(channel, KAFKA_HANDOFF_CHANNELS) ? (
+              <a
+                href={kafkaUiTopicUrl(kafkaUi, channel.address) ?? kafkaUi}
+                target="_blank"
+                rel="noreferrer"
+                className="mono inline-flex shrink-0 items-center gap-1 whitespace-nowrap rounded-control text-accent hover:underline"
+                title={`Open ${channel.address} in Kafka UI`}
+              >
+                view in Kafka UI <ExternalLink size={12} aria-hidden />
+              </a>
             ) : null}
           </div>
           {channel.doc ? (

package/src/components/LifecycleDiagram.tsx

@@ -3,6 +3,12 @@ import type { Aggregate } from "../catalog";
 import { layoutLifecycle, METRICS } from "../lib/lifecycle";
 import { KindIcon } from "./kind";
 
+function transitionTone(on: string) {
+  if (on === "Fail") return { color: "var(--status-unresolved)", marker: "lc-arrow-fail" };
+  if (on === "Succeed") return { color: "var(--status-verified)", marker: "lc-arrow-succeed" };
+  return { color: "var(--fg-muted)", marker: "lc-arrow" };
+}
+
 /**
  * The aggregate's state machine, as the code wrote it down. Boxes and arrows
  * are SVG; the labels are HTML laid over it, because a label holds a link to
@@ -29,18 +35,27 @@ export function LifecycleDiagram({
             <marker id="lc-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
               <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--fg-muted)" />
             </marker>
+            <marker id="lc-arrow-fail" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+              <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--status-unresolved)" />
+            </marker>
+            <marker id="lc-arrow-succeed" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+              <path d="M 0 0 L 8 4 L 0 8 z" fill="var(--status-verified)" />
+            </marker>
           </defs>
-          {edges.map((e) => (
-            <path
-              key={`${e.from}-${e.to}-${e.on}`}
-              d={e.path}
-              fill="none"
-              stroke="var(--fg-muted)"
-              strokeWidth={1.25}
-              strokeDasharray={e.back ? "4 3" : undefined}
-              markerEnd="url(#lc-arrow)"
-            />
-          ))}
+          {edges.map((e) => {
+            const tone = transitionTone(e.on);
+            return (
+              <path
+                key={`${e.from}-${e.to}-${e.on}`}
+                d={e.path}
+                fill="none"
+                stroke={tone.color}
+                strokeWidth={1.25}
+                strokeDasharray={e.back ? "4 3" : undefined}
+                markerEnd={`url(#${tone.marker})`}
+              />
+            );
+          })}
           {boxes.map((b) => (
             <g key={b.state}>
               <rect
@@ -80,11 +95,12 @@ export function LifecycleDiagram({
         ))}
         {edges.map((e) => {
           const to = e.emits ? eventPath(e.emits) : null;
+          const tone = transitionTone(e.on);
           return (
             <div
               key={`${e.from}-${e.to}-${e.on}-label`}
               className="mono absolute flex -translate-x-1/2 -translate-y-1/2 items-center gap-1 whitespace-nowrap rounded-control bg-bg px-1 text-muted"
-              style={{ left: e.labelX, top: e.labelY }}
+              style={{ left: e.labelX, top: e.labelY, color: tone.color }}
               title={e.source ? `made at ${e.source}` : undefined}
             >
               {e.on}

package/src/components/ProblemRow.tsx

@@ -31,6 +31,7 @@ const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
   "shared-channel": "event",
   "channel-undeclared": "event",
   "channel-unpublished": "service",
+  "message-encoding": "service",
   "subscription-unresolved": "service",
 };
 
@@ -50,6 +51,7 @@ const KIND_NOTE: Record<Problem["kind"], string> = {
   "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",
 };
@@ -72,6 +74,7 @@ function nearPath(problem: Problem): string | null {
     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":
@@ -110,6 +113,7 @@ function peerPath(problem: Problem): string | null {
       );
     case "shared-store":
     case "shared-channel":
+    case "message-encoding":
       return servicePath(problem.peer);
     case "outbox-payload":
       return storePath(problem.peer);

package/src/components/WhatLinksHere.tsx

@@ -14,7 +14,11 @@ import { useMemo } from "react";
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { catalog, index } from "../data";
-import { backlinkCount, backlinksFor } from "../lib/backlinks";
+import {
+  backlinkCount,
+  backlinksFor,
+  distinctBacklinks,
+} from "../lib/backlinks";
 import type { Backlink, BacklinkGroup, BacklinkTarget } from "../lib/backlinks";
 import { plural } from "../lib/format";
 import { KIND_LABEL, KIND_PLURAL } from "../lib/kinds";
@@ -163,9 +167,7 @@ export function WhatLinksHere({
         className={`mono flex flex-wrap items-center gap-1.5 text-muted ${className || "mt-2"}`}
       >
         linked from
-        {groups
-          .flatMap((g) => g.links)
-          .map((link) => {
+        {distinctBacklinks(groups).map((link) => {
             const to = backlinkPath(link);
             const body = (
               <>

package/src/enrich.test.ts

@@ -864,14 +864,13 @@ describe("enrichCatalog: calls from rpc steps", () => {
     expect(() => validateCatalog(catalog)).not.toThrow();
   });
 
-  it("is what lets a step naming a provided method validate: the call is now known", () => {
-    // The validator resolves a step's ref against declared calls, not against
-    // what peers provide. Before this pass the step names a method no service
-    // is on record as calling; after it, shop.oms is.
+  it("keeps a step naming a provided method valid while recording its caller", () => {
+    // The provided method is enough to resolve the flow step. Enrichment adds
+    // the separate fact that shop.oms is one of its callers.
     const c = estate([
       flow("a", [step("shop.oms", "shop.pricing", "rpc", { ref: METHOD })]),
     ]);
-    expect(() => validateCatalog(c)).toThrow(/resolves to neither/);
+    expect(() => validateCatalog(c)).not.toThrow();
     expect(() => validateCatalog(enrichCatalog(c).catalog)).not.toThrow();
   });
 

package/src/flow/StepDetail.tsx

@@ -1,18 +1,17 @@
 import { useMemo } from "react";
 import { Link } from "react-router";
-import { AlertTriangle } from "lucide-react";
+import { AlertTriangle, FileCode2 } from "lucide-react";
 import { allRepos, stepFrames } from "../catalog";
 import type { Flow, Step, StepFrame } from "../catalog";
 import { catalog, index } from "../data";
 import { Ident } from "../components/Ident";
-import { EditorLink } from "../components/EditorLink";
-import { SourcePreviewButton } from "../components/SourcePreview";
+import { SourcePreviewLink } from "../components/SourcePreview";
 import { flowRepoService } from "../lib/derive";
 import { sourceLocation } from "../lib/source-link";
 import { AdrNumber, StatusChip } from "../components/primitives";
 import { ShapeRows } from "../components/ShapeRows";
 import { shapeFor } from "../components/MethodRows";
-import { stepAnswer } from "./answers";
+import { stepAnswer, stepRpcContract } from "./answers";
 import {
   aggregatePath,
   paths,
@@ -154,12 +153,28 @@ function EventDetail({ step, flow }: { step: Step; flow: Flow }) {
 }
 
 function RpcDetail({ step, flow }: { step: Step; flow: Flow }) {
-  const method = step.ref ?? step.label ?? "(unknown method)";
+  const contract = stepRpcContract(index, step);
+  const method = contract?.id ?? step.ref ?? step.label ?? "(unknown method)";
   const call = step.ref ? index.rpcById.get(step.ref) : undefined;
-  const provider = step.ref
-    ? index.rpcProviderByMethod.get(step.ref)
+  const provider = contract?.provider;
+  const internalProvider = provider
+    ? index.serviceById.get(provider.id)
     : undefined;
-  const providerPath = provider ? servicePath(provider.id) : null;
+  const providerPath = internalProvider ? servicePath(internalProvider.id) : null;
+  const requestFields = contract
+    ? shapeFor(
+        contract.provided,
+        contract.method.request,
+        contract.method.requestRef,
+      )
+    : null;
+  const responseFields = contract
+    ? shapeFor(
+        contract.provided,
+        contract.method.response,
+        contract.method.responseRef,
+      )
+    : null;
   // The flow records the hop; what comes back is the contract's to say.
   const answer = stepAnswer(index, step);
 
@@ -185,10 +200,12 @@ function RpcDetail({ step, flow }: { step: Step; flow: Flow }) {
           ) : null}
           <dt className="mono text-muted">Provider</dt>
           <dd>
-            {provider && providerPath ? (
+            {internalProvider && providerPath ? (
               <Link to={providerPath} className="mono text-accent">
-                {provider.id} →
+                {internalProvider.id} →
               </Link>
+            ) : provider ? (
+              <span className="mono text-ink">{provider.id}</span>
             ) : (
               <span className="mono inline-flex items-center gap-1.5 rounded-control border px-1.5 py-0.5 status-unresolved">
                 <AlertTriangle size={11} aria-hidden />
@@ -205,6 +222,34 @@ function RpcDetail({ step, flow }: { step: Step; flow: Flow }) {
         </dl>
       </DetailSection>
 
+      {contract?.method.request ? (
+        <DetailSection title="Request" meta={contract.method.request}>
+          {requestFields ? (
+            <ShapeRows
+              fields={requestFields}
+              enums={contract.provided.enums}
+              showHeader
+            />
+          ) : (
+            <div className="mono text-muted">shape not recorded</div>
+          )}
+        </DetailSection>
+      ) : null}
+
+      {contract?.method.response ? (
+        <DetailSection title="Response" meta={contract.method.response}>
+          {responseFields ? (
+            <ShapeRows
+              fields={responseFields}
+              enums={contract.provided.enums}
+              showHeader
+            />
+          ) : (
+            <div className="mono text-muted">shape not recorded</div>
+          )}
+        </DetailSection>
+      ) : null}
+
       <DetailSection title="Source">
         {call ? (
           <SourceWhere where={call.source} flow={flow} structured />
@@ -525,48 +570,25 @@ function SourceWhere({
     allRepos(catalog),
   );
 
-  const actions = (
-    <>
-      <SourcePreviewButton
-        location={location}
-        className="border px-2 py-1 border-line bg-canvas hover:bg-raised hover:no-underline"
-      />
-      {location?.href ? (
-        <a
-          href={location.href}
-          target="_blank"
-          rel="noreferrer"
-          className="mono inline-flex items-center rounded-control border px-2 py-1 border-line bg-canvas text-accent hover:bg-raised"
-          title="Open on the forge, at the built commit"
-        >
-          forge ↗
-        </a>
-      ) : null}
-      <EditorLink
-        location={location}
-        variant="text"
-        className="inline-flex items-center border px-2 py-1 border-line bg-canvas hover:bg-raised hover:no-underline"
-      />
-    </>
+  const source = (
+    <SourcePreviewLink
+      location={location}
+      className={
+        structured
+          ? "w-full min-w-0 border px-2.5 py-2 border-line bg-canvas text-ink hover:border-line-strong hover:bg-raised hover:no-underline"
+          : "max-w-full min-w-0 text-muted hover:text-accent"
+      }
+    >
+      <FileCode2 size={14} aria-hidden className="shrink-0" />
+      <span className="min-w-0 break-all text-left">{where}</span>
+    </SourcePreviewLink>
   );
 
   if (structured) {
-    return (
-      <div className="flex min-w-0 flex-col gap-2">
-        <div className="mono min-w-0 break-all text-muted">
-          <Ident block value={where} className="text-muted" />
-        </div>
-        <div className="flex flex-wrap items-center gap-1.5">{actions}</div>
-      </div>
-    );
+    return <div className="min-w-0">{source}</div>;
   }
 
-  return (
-    <div className="mono flex flex-wrap items-center gap-2 break-all text-muted">
-      <Ident block value={where} className="text-muted" />
-      {actions}
-    </div>
-  );
+  return <div className="min-w-0">{source}</div>;
 }
 
 function Where({ step, flow }: { step: Step; flow: Flow }) {
@@ -574,6 +596,34 @@ function Where({ step, flow }: { step: Step; flow: Flow }) {
   return <SourceWhere where={step.line} flow={flow} />;
 }
 
+function CallDetail({ step, flow }: { step: Step; flow: Flow }) {
+  return (
+    <section
+      aria-label="Call detail"
+      className="overflow-hidden rounded-card border shadow-xs border-line"
+    >
+      <header className="border-b px-3 py-2.5 border-line bg-surface">
+        <h2 className="label">Call</h2>
+        <div className="mt-2">
+          <Ident
+            block
+            value={step.label ?? "internal call"}
+            className="text-ink"
+          />
+        </div>
+      </header>
+
+      <DetailSection title="Source">
+        {step.line ? (
+          <SourceWhere where={step.line} flow={flow} structured />
+        ) : (
+          <div className="mono text-muted">not recorded</div>
+        )}
+      </DetailSection>
+    </section>
+  );
+}
+
 function StoreCallDetail({ step, flow }: { step: Step; flow: Flow }) {
   const access = step.storeAccess!;
   const store = index.storeById.get(access.store);
@@ -699,13 +749,7 @@ export function StepDetailBody({ step, flow }: { step: Step; flow: Flow }) {
       ) : step.storeAccess ? (
         <StoreCallDetail step={step} flow={flow} />
       ) : (
-        <>
-          <div className="mono text-[13px]">
-            {step.label ?? "internal call"}
-          </div>
-          <Label>Source</Label>
-          <Where step={step} flow={flow} />
-        </>
+        <CallDetail step={step} flow={flow} />
       )}
 
       {step.note ? (

package/src/flow/answers.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { catalog, index } from "../data";
 import { walkSteps } from "../catalog";
-import { flowAnswers, stepAnswer } from "./answers";
+import { flowAnswers, stepAnswer, stepRpcContract } from "./answers";
 
 const flow = (slug: string) => {
   const found = catalog.flows.find((f) => f.slug === slug);
@@ -16,6 +16,23 @@ const step = (slug: string, id: string) => {
 };
 
 describe("stepAnswer", () => {
+  it("resolves an incoming endpoint to its full request and response contract", () => {
+    const contract = stepRpcContract(
+      index,
+      step("pricing-archive-price-list", "s1"),
+    );
+
+    expect(contract?.id).toBe("shop.v1.PriceLists/ArchivePriceList");
+    expect(contract?.provider.id).toBe("shop.pricing");
+    expect(contract?.method.request).toBe("ArchivePriceListRequest");
+    expect(contract?.method.response).toBe("ArchivePriceListResponse");
+    expect(
+      contract?.provided.messages?.find(
+        (message) => message.name === contract.method.request,
+      )?.fields.map((field) => field.name),
+    ).toEqual(["price_list_id"]);
+  });
+
   it("reads the answer of an endpoint off the document that declares it", () => {
     // billing's ViewSet is exposed by billing.v1.Invoices, and the document
     // says a void answers 204 and an issue answers with the invoice's id.