@shortlink-org/portolan 0.2.3 → 0.2.4

package/src/flow/answers.ts

@@ -9,14 +9,33 @@
 // queryset - which no interface in the catalog describes; an event is a
 // publication, and drawing a reply to it would be a lie about the bus.
 
-import type { CatalogIndex, Flow, RpcMethod, Step } from "../catalog";
+import type {
+  CatalogIndex,
+  External,
+  Flow,
+  RpcMethod,
+  RpcService,
+  Service,
+  Step,
+} from "../catalog";
 import { walkSteps } from "../catalog";
 
-/** The method a step reaches, when the catalog has it. */
-function methodOf(index: CatalogIndex, step: Step): RpcMethod | undefined {
+export interface StepRpcContract {
+  id: string;
+  provider: Service | External;
+  provided: RpcService;
+  method: RpcMethod;
+}
+
+/** The interface and method an RPC step reaches, when the catalog has them. */
+export function stepRpcContract(
+  index: CatalogIndex,
+  step: Step,
+): StepRpcContract | undefined {
   if (step.kind !== "rpc") return undefined;
 
-  // Outgoing: the step names the call, and the call id is `<interface>/<method>`.
+  // A recorded ref is the full `<interface>/<method>` id, whether the flow
+  // enters this service or calls another one.
   if (step.ref) {
     const cut = step.ref.lastIndexOf("/");
     if (cut < 0) return undefined;
@@ -26,22 +45,32 @@ function methodOf(index: CatalogIndex, step: Step): RpcMethod | undefined {
     const provider =
       index.rpcProviderByMethod.get(step.ref) ?? index.externalProviderByMethod.get(step.ref);
     const provided = provider?.provides.find((p) => p.id === interfaceId);
-    return provided?.methods.find((m) => m.name === name);
+    const method = provided?.methods.find((m) => m.name === name);
+    if (!provider || !provided || !method) return undefined;
+    return { id: step.ref, provider, provided, method };
   }
 
-  // Incoming: somebody called this service, and the label is the operation.
+  // Older incoming flows recorded only the operation label. Keep resolving
+  // those catalogs while new extractors write the full ref above.
   const service = index.serviceById.get(step.to);
   if (!service || !step.label) return undefined;
   for (const provided of service.provides) {
     const found = provided.methods.find((m) => m.name === step.label);
-    if (found) return found;
+    if (found) {
+      return {
+        id: `${provided.id}/${found.name}`,
+        provider: service,
+        provided,
+        method: found,
+      };
+    }
   }
   return undefined;
 }
 
 /** What the callee hands back, as the contract names it. */
 export function stepAnswer(index: CatalogIndex, step: Step): string | undefined {
-  return methodOf(index, step)?.response || undefined;
+  return stepRpcContract(index, step)?.method.response || undefined;
 }
 
 /** Every request without an explicit response step that has an answer. */

package/src/lib/backlinks.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 import { catalog, index } from "../testing/estate";
-import { backlinkCount, backlinksFor, stepsInto } from "./backlinks";
+import {
+  backlinkCount,
+  backlinksFor,
+  distinctBacklinks,
+  stepsInto,
+} from "./backlinks";
 import type { BacklinkGroup, BacklinkTarget } from "./backlinks";
 import type { Kind } from "./kinds";
 
@@ -290,6 +295,16 @@ describe("grouping", () => {
     const g = groups({ kind: "service", id: "shop.oms" });
     expect(backlinkCount(g)).toBe(g.reduce((n, x) => n + x.links.length, 0));
   });
+
+  it("collapses repeated entities for compact backlink lines", () => {
+    const links = distinctBacklinks(
+      groups({ kind: "store", id: "shop.oms.pg" }),
+    );
+    const ids = links.map((link) => `${link.kind}:${link.id}`);
+
+    expect(ids).toEqual([...new Set(ids)]);
+    expect(ids).toContain("aggregate:shop.oms.order");
+  });
 });
 
 describe("the word that names it", () => {

package/src/lib/backlinks.ts

@@ -100,6 +100,26 @@ export function backlinkCount(groups: readonly BacklinkGroup[]): number {
   return groups.reduce((n, g) => n + g.links.length, 0);
 }
 
+/**
+ * One link per entity for compact surfaces that cannot show each link's
+ * reason. The full section deliberately keeps separate edges (for example an
+ * aggregate persisted by two tables), but two identical chips would only look
+ * like an accidental duplicate when `via` is not visible.
+ */
+export function distinctBacklinks(
+  groups: readonly BacklinkGroup[],
+): Backlink[] {
+  const seen = new Set<string>();
+  return groups.flatMap((group) =>
+    group.links.filter((link) => {
+      const key = `${link.kind}:${link.id}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    }),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Row builders. One per kind of thing that can do the pointing.
 // ---------------------------------------------------------------------------

package/src/lib/catalog-diff.test.ts

@@ -57,6 +57,24 @@ describe("diffCatalogs", () => {
 });
 
 describe("diffCatalogs: what a reviewer is looking for", () => {
+  it("calls a change between known message encodings breaking", () => {
+    const before = JSON.parse(JSON.stringify(catalog)) as Catalog;
+    const service = before.contexts[0]!.services[0]!;
+    service.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "json" }],
+    }];
+    const after = JSON.parse(JSON.stringify(before)) as Catalog;
+    after.contexts[0]!.services[0]!.channels![0]!.messages[0]!.encoding = "msgpack";
+
+    expect(diffCatalogs(before, after)).toEqual([{
+      kind: "message.encoding",
+      severity: "breaking",
+      where: service.id,
+      summary: "send message cart.BasketCreated on shop.cart.basket uses msgpack, was json",
+    }]);
+  });
+
   // The finding the whole report exists for.
   it("names a new event nothing consumes", () => {
     const changes = edited((c) => {

package/src/lib/catalog-diff.ts

@@ -331,7 +331,7 @@ function diffCalls(before: Service, after: Service, add: Add): void {
 function diffChannels(before: Service, after: Service, add: Add): void {
   const was = byId(before.channels ?? [], (c) => c.address);
   const now = byId(after.channels ?? [], (c) => c.address);
-  const { added, removed } = partition(was, now);
+  const { added, removed, kept } = partition(was, now);
 
   for (const address of added) {
     add("channel.added", "addition", before.id, `"${before.id}" declares channel ${address}`);
@@ -339,6 +339,24 @@ function diffChannels(before: Service, after: Service, add: Add): void {
   for (const address of removed) {
     add("channel.removed", "breaking", before.id, `"${before.id}" no longer declares channel ${address}`);
   }
+  for (const address of kept) {
+    const previous = byId(was.get(address)!.messages, (message) => `${message.direction} ${message.name}`);
+    const current = byId(now.get(address)!.messages, (message) => `${message.direction} ${message.name}`);
+    const messages = partition(previous, current).kept;
+    for (const id of messages) {
+      const a = previous.get(id)!;
+      const b = current.get(id)!;
+      const from = a.encoding || a.contentType || "";
+      const to = b.encoding || b.contentType || "";
+      if (from === to) continue;
+      add(
+        "message.encoding",
+        from && to ? "breaking" : "change",
+        before.id,
+        `${a.direction} message ${a.name} on ${address} uses ${to || "an unspecified encoding"}, was ${from || "unspecified"}`,
+      );
+    }
+  }
 }
 
 function diffServiceStores(before: Service, after: Service, add: Add): void {

package/src/lib/derive.ts

@@ -424,6 +424,7 @@ export type ProblemKind =
   | "shared-channel"
   | "channel-undeclared"
   | "channel-unpublished"
+  | "message-encoding"
   | "subscription-unresolved";
 
 /**

package/src/lib/kafka-ui.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Channel } from "../catalog";
+import {
+  isKafkaChannel,
+  kafkaHandoffChannels,
+  kafkaUiTopicUrl,
+  normalizeKafkaUiUrl,
+} from "./kafka-ui";
+
+describe("Kafka UI integration", () => {
+  it("accepts web URLs and rejects values that cannot be opened safely", () => {
+    expect(normalizeKafkaUiUrl(" https://kafka.example/ ")).toBe(
+      "https://kafka.example",
+    );
+    expect(normalizeKafkaUiUrl("javascript:alert(1)")).toBeNull();
+    expect(normalizeKafkaUiUrl("not a URL")).toBeNull();
+    expect(normalizeKafkaUiUrl("  ")).toBe("");
+  });
+
+  it("opens the exact topic from a Kafbat cluster URL behind a path prefix", () => {
+    expect(
+      kafkaUiTopicUrl(
+        "https://ops.example/kafka/ui/clusters/prod/all-topics/old",
+        "orders/new",
+      ),
+    ).toBe(
+      "https://ops.example/kafka/ui/clusters/prod/all-topics/orders%2Fnew",
+    );
+  });
+
+  it("keeps a plain installation URL as the useful fallback", () => {
+    expect(kafkaUiTopicUrl("https://kafka.example", "orders.created")).toBe(
+      "https://kafka.example",
+    );
+  });
+
+  it("recognizes both Kafka-labelled cards and explicit Kafka handoffs", () => {
+    const labelled: Channel = {
+      address: "orders.created",
+      title: "Kafka · orders.created",
+      messages: [],
+    };
+    const flowOnly: Channel = {
+      address: "payments.accepted",
+      title: "message stream",
+      messages: [],
+    };
+    const nats: Channel = {
+      address: "shop.cart",
+      title: "JetStream subject",
+      messages: [],
+    };
+    const catalog = {
+      flows: [
+        {
+          id: "payment-kafka",
+          slug: "payment-kafka",
+          name: "Payment Kafka",
+          summary: "",
+          owner: "payments",
+          participants: [],
+          steps: [
+            {
+              type: "step",
+              id: "publish",
+              from: "payments",
+              to: "broker",
+              kind: "event",
+              status: "verified",
+              handoff: {
+                kind: "message",
+                transport: "kafka",
+                channel: "payments.accepted",
+                direction: "send",
+              },
+            },
+          ],
+        },
+      ],
+    } as Pick<Catalog, "flows">;
+    const handoffs = kafkaHandoffChannels(catalog);
+
+    expect(isKafkaChannel(labelled, handoffs)).toBe(true);
+    expect(isKafkaChannel(flowOnly, handoffs)).toBe(true);
+    expect(isKafkaChannel(nats, handoffs)).toBe(false);
+  });
+});

package/src/lib/kafka-ui.ts

@@ -0,0 +1,105 @@
+// The optional hand-off from a catalogued Kafka topic to the operational UI.
+//
+// The configured value belongs to the reader, not to the catalog: two readers
+// can use different Kafka UI installations for the same generated estate. It
+// therefore lives in localStorage, like the editor and display preferences.
+// A cluster URL gives us enough information to open the exact topic; a plain
+// installation URL remains useful and opens Kafka UI without inventing a
+// cluster name.
+
+import { create } from "zustand";
+import type { Catalog, Channel } from "../catalog";
+import { walkSteps } from "../catalog";
+
+export const KAFKA_UI_KEY = "portolan.integrations.kafka-ui";
+
+export function normalizeKafkaUiUrl(value: string): string | null {
+  const clean = value.trim();
+  if (!clean) return "";
+  try {
+    const url = new URL(clean);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/** Build Kafbat's topic route when the configured URL names a cluster. */
+export function kafkaUiTopicUrl(
+  configured: string,
+  topic: string,
+): string | null {
+  const normalized = normalizeKafkaUiUrl(configured);
+  if (!normalized) return null;
+  const url = new URL(normalized);
+  const match = url.pathname.match(
+    /^(.*\/ui\/clusters\/[^/]+)(?:\/.*)?$/,
+  );
+  if (!match?.[1]) return normalized;
+  url.pathname = `${match[1]}/all-topics/${encodeURIComponent(topic)}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+/** Topic addresses whose source-backed flow explicitly says Kafka. */
+export function kafkaHandoffChannels(catalog: Pick<Catalog, "flows">): Set<string> {
+  const channels = new Set<string>();
+  for (const flow of catalog.flows) {
+    for (const step of walkSteps(flow.steps)) {
+      if (step.handoff?.transport.toLowerCase() === "kafka") {
+        channels.add(step.handoff.channel);
+      }
+    }
+  }
+  return channels;
+}
+
+/**
+ * A channel is Kafka only when an extractor said so in its presentation facts
+ * or a matching flow carries explicit Kafka transport evidence. Channel itself
+ * predates the transport field, so address alone is deliberately insufficient.
+ */
+export function isKafkaChannel(
+  channel: Pick<Channel, "address" | "title" | "doc">,
+  handoffChannels: ReadonlySet<string>,
+): boolean {
+  const description = `${channel.title ?? ""} ${channel.doc ?? ""}`;
+  return /(^|[^a-z0-9])kafka([^a-z0-9]|$)/i.test(description)
+    || handoffChannels.has(channel.address);
+}
+
+function read(): string {
+  try {
+    const value = localStorage.getItem(KAFKA_UI_KEY) ?? "";
+    return normalizeKafkaUiUrl(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function write(value: string): void {
+  try {
+    if (value) localStorage.setItem(KAFKA_UI_KEY, value);
+    else localStorage.removeItem(KAFKA_UI_KEY);
+  } catch {
+    /* private mode: keep the value for this session */
+  }
+}
+
+interface KafkaUiState {
+  url: string;
+  setUrl: (url: string) => void;
+}
+
+export const useKafkaUi = create<KafkaUiState>()((set) => ({
+  url: read(),
+  setUrl: (url) => {
+    const normalized = normalizeKafkaUiUrl(url);
+    if (normalized === null) return;
+    write(normalized);
+    set({ url: normalized });
+  },
+}));

package/src/lib/wire-problems.test.ts

@@ -260,4 +260,25 @@ describe("wireProblems", () => {
     ]);
     expect(unresolved[0]?.severity).toBe("warning");
   });
+
+  it("reports a MessagePack subscriber paired with a JSON publisher", () => {
+    const publisherChannel = channel("inventory.snapshots", "send inventory.Snapshot");
+    publisherChannel.messages[0]!.encoding = "json";
+    const subscriberChannel = channel("inventory.snapshots", "receive inventory.Snapshot");
+    subscriberChannel.messages[0]!.encoding = "msgpack";
+    const publisher = speaking(service("shop.inventory", []), publisherChannel);
+    const subscriber = speaking(service("shop.search", []), subscriberChannel);
+
+    const mismatch = found(catalogWith([publisher, subscriber])).find(
+      (problem) => problem.kind === "message-encoding",
+    );
+    expect(mismatch).toMatchObject({
+      severity: "error",
+      service: "shop.search",
+      peer: "shop.inventory",
+    });
+    expect(mismatch?.note).toContain("expects inventory.Snapshot");
+    expect(mismatch?.note).toContain("msgpack");
+    expect(mismatch?.note).toContain("json");
+  });
 });

package/src/lib/wire-problems.ts

@@ -19,7 +19,7 @@
 // merged catalog, for the same reason the store rule is: each extractor sees
 // one repository and cannot know what another declares.
 
-import type { Catalog, CatalogIndex, Event, Service } from "../catalog";
+import type { Catalog, CatalogIndex, ChannelMessage, Event, Service } from "../catalog";
 import type { Problem } from "./derive";
 
 interface Publisher {
@@ -38,10 +38,71 @@ export function wireProblems(
   return [
     ...sharedChannels(catalog),
     ...documentAgainstCode(catalog),
+    ...messageEncodingMismatches(catalog),
     ...unresolvedSubscriptions(catalog, index),
   ];
 }
 
+interface MessageEndpoint {
+  context: string;
+  service: Service;
+  address: string;
+  source?: string;
+  message: ChannelMessage;
+}
+
+/** Producer and subscriber have both named a format, and those formats differ. */
+function messageEncodingMismatches(catalog: Catalog): Problem[] {
+  const sends = new Map<string, MessageEndpoint[]>();
+  const receives: MessageEndpoint[] = [];
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const channel of service.channels ?? []) {
+        for (const message of channel.messages) {
+          const endpoint = { context: context.id, service, address: channel.address, source: channel.source, message };
+          const key = `${channel.address}\u0000${message.name}`;
+          if (message.direction === "send") {
+            const publishers = sends.get(key) ?? [];
+            publishers.push(endpoint);
+            sends.set(key, publishers);
+          } else {
+            receives.push(endpoint);
+          }
+        }
+      }
+    }
+  }
+
+  const out: Problem[] = [];
+  for (const receiver of receives) {
+    const expected = wireFormat(receiver.message);
+    if (!expected) continue;
+    const key = `${receiver.address}\u0000${receiver.message.name}`;
+    for (const publisher of sends.get(key) ?? []) {
+      const actual = wireFormat(publisher.message);
+      if (!actual || actual === expected) continue;
+      out.push({
+        kind: "message-encoding",
+        severity: "error",
+        context: receiver.context,
+        service: receiver.service.id,
+        id: receiver.service.id,
+        peer: publisher.service.id,
+        note: `${receiver.service.id} expects ${receiver.message.name} on ${receiver.address} as ${expected}, but ${publisher.service.id} sends it as ${actual}.`,
+        source: receiver.source,
+      });
+    }
+  }
+  return out;
+}
+
+function wireFormat(message: ChannelMessage): string {
+  if (message.encoding) return message.encoding.trim().toLowerCase();
+  const contentType = message.contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  if (contentType.includes("msgpack") || contentType.includes("messagepack")) return "msgpack";
+  return contentType;
+}
+
 /**
  * Every service that publishes on a channel another service publishes on
  * too: one row per service per such channel, pointing at the other side.

package/src/likec4/FlowView.tsx

@@ -100,18 +100,14 @@ export function FlowView({
 
   const highlightEdges = useMemo(
     () =>
-      marked
-        .map((stepId) => pairing.edgeOf.get(stepId))
-        .filter((id): id is string => id !== undefined),
+      marked.flatMap((stepId) => pairing.edgesOf.get(stepId) ?? []),
     [marked, pairing],
   );
 
   const focusedPathEdges = useMemo(
     () =>
       pathSteps
-        ? pathSteps
-            .map((stepId) => pairing.edgeOf.get(stepId))
-            .filter((id): id is string => id !== undefined)
+        ? pathSteps.flatMap((stepId) => pairing.edgesOf.get(stepId) ?? [])
         : null,
     [pathSteps, pairing],
   );

package/src/likec4/flow-edges.test.ts

@@ -1,8 +1,13 @@
 import { describe, expect, it } from "vitest";
 import { catalog } from "../data";
+import type { Flow } from "../catalog";
 import { walkSteps } from "../catalog";
 import { hiddenStepIds } from "../flow/cross-context";
-import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+import {
+  drawnEdgeStepIds,
+  drawnStepIds,
+  pairEdgesToSteps,
+} from "./flow-edges";
 
 describe("pairEdgesToSteps", () => {
   it("pairs by position, both ways", () => {
@@ -14,6 +19,16 @@ describe("pairEdgesToSteps", () => {
     expect(pairing.edgeOf.get("s3")).toBe("step-02:par.02");
   });
 
+  it("pairs a request and its generated response to the same catalog step", () => {
+    const pairing = pairEdgesToSteps(
+      ["step-01", "step-02"],
+      ["request", "request"],
+    );
+    expect(pairing.stepOf.get("step-02")).toBe("request");
+    expect(pairing.edgeOf.get("request")).toBe("step-01");
+    expect(pairing.edgesOf.get("request")).toEqual(["step-01", "step-02"]);
+  });
+
   /**
    * A length mismatch means the generator and the view have drifted. Guessing
    * would light the wrong arrow, which is worse than lighting none, so the
@@ -23,6 +38,7 @@ describe("pairEdgesToSteps", () => {
     const pairing = pairEdgesToSteps(["step-01"], ["s1", "s2"]);
     expect(pairing.stepOf.size).toBe(0);
     expect(pairing.edgeOf.size).toBe(0);
+    expect(pairing.edgesOf.size).toBe(0);
   });
 });
 
@@ -49,3 +65,50 @@ describe("drawnStepIds", () => {
     }
   });
 });
+
+describe("drawnEdgeStepIds", () => {
+  it("returns nested RPC responses in place and the actor response at the end", () => {
+    const flow: Flow = {
+      id: "flow.checkout",
+      slug: "checkout",
+      name: "Checkout",
+      summary: "",
+      owner: "shop",
+      participants: [
+        { id: "client", kind: "actor", context: null },
+        { id: "shop.cart", kind: "service", context: "shop" },
+        { id: "auth.auth", kind: "service", context: "auth" },
+      ],
+      steps: [
+        {
+          type: "step",
+          id: "root",
+          from: "client",
+          to: "shop.cart",
+          kind: "rpc",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "nested",
+          from: "shop.cart",
+          to: "auth.auth",
+          kind: "rpc",
+          status: "declared",
+        },
+        {
+          type: "step",
+          id: "done",
+          from: "shop.cart",
+          to: "client",
+          kind: "event",
+          status: "declared",
+        },
+      ],
+    };
+
+    expect(
+      drawnEdgeStepIds(flow, false, new Set(["root", "nested"])),
+    ).toEqual(["root", "nested", "nested", "done", "root"]);
+  });
+});