@shortlink-org/portolan 0.2.2 → 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/index.css

@@ -573,22 +573,6 @@
     background: color-mix(in srgb, var(--accent) 10%, transparent);
   }
 
-  /* Sanctioned gradient 2 - the accent surface. Reserved for a primary button;
-     white on --accent-lo clears 4.5:1 in both themes. */
-  .btn-accent {
-    @apply mono flex items-center gap-1.5 rounded-control px-3 py-1.5;
-    color: #fff;
-    background-image: linear-gradient(
-      to bottom,
-      var(--accent-hi),
-      var(--accent-lo)
-    );
-    transition: filter var(--dur-micro) var(--ease-out);
-  }
-  .btn-accent:hover {
-    filter: brightness(1.06);
-  }
-
   /* The landing's primary action should feel like a control from the map,
      not a bright rectangle pasted over it. The depth is always present; the
      brief chart-line sweep only appears when a reader points at the action. */
@@ -697,7 +681,6 @@
     outline: 2px solid color-mix(in srgb, var(--accent) 55%, white);
     outline-offset: 3px;
   }
-  .btn-accent:disabled,
   .product-primary:disabled,
   .tbtn:disabled {
     cursor: not-allowed;

package/src/landing/LandingPage.tsx

@@ -97,7 +97,7 @@ function Header() {
           >
             <GitBranch size={15} /> GitHub
           </a>
-          <Link to={exampleTo} className="btn-accent landing-primary">
+          <Link to={exampleTo} className="landing-primary">
             Explore example <ArrowRight size={14} />
           </Link>
         </div>
@@ -319,7 +319,7 @@ export function LandingPage() {
               >
                 <Link
                   to={exampleTo}
-                  className="btn-accent landing-primary px-4 py-2.5"
+                  className="landing-primary px-4 py-2.5"
                 >
                   Explore example catalog <ArrowRight size={15} />
                 </Link>
@@ -647,7 +647,7 @@ export function LandingPage() {
               <div className="mt-4 flex flex-wrap gap-3">
                 <Link
                   to={exampleTo}
-                  className="btn-accent landing-primary px-4 py-2.5"
+                  className="landing-primary px-4 py-2.5"
                 >
                   Open the example <ArrowRight size={15} />
                 </Link>
@@ -719,7 +719,7 @@ export function LandingPage() {
             <div className="mt-8 flex flex-wrap justify-center gap-3">
               <Link
                 to={exampleTo}
-                className="btn-accent landing-primary px-4 py-2.5"
+                className="landing-primary px-4 py-2.5"
               >
                 Explore example catalog <ArrowRight size={15} />
               </Link>

package/src/lib/all-problems.ts

@@ -1,7 +1,7 @@
 // Every reading the catalog makes of itself, in one list.
 //
 // Four readers, each answering a different question: edges that resolve to
-// nothing, schemas that name a method the module lacks, tables and columns
+// nothing, producer and consumer schemas that disagree, tables and columns
 // that disagree with the model, and channels that documents and events do not
 // agree on. The problems page, the overview and the landing all want the
 // union, errors first - a boundary leak is not the same kind of news as a

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

@@ -420,9 +420,11 @@ export type ProblemKind =
   | "column-type"
   | "outbox-payload"
   | "proto-missing"
+  | "proto-drift"
   | "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/local-api.ts

@@ -70,10 +70,20 @@ export interface GeneratedFileDiff {
 }
 
 export type DeliveryProvider = "github" | "gitlab";
+export type DeliveryFeatureId = "check" | "diff" | "sarif" | "pages";
+
+export interface DeliveryFeature {
+  id: DeliveryFeatureId;
+  label: string;
+  description: string;
+  selected: boolean;
+  available: boolean;
+  requires: DeliveryFeatureId[];
+}
 
 export interface DeliveryPresetFile {
   path: string;
-  status: "added" | "changed" | "unchanged" | "conflict";
+  status: "added" | "changed" | "removed" | "unchanged" | "conflict";
   diff: string;
   message?: string;
 }
@@ -86,7 +96,7 @@ export interface DeliveryPreset {
   defaultBranch: string;
   status: "available" | "installed" | "update" | "conflict";
   revision: string;
-  features: string[];
+  features: DeliveryFeature[];
   files: DeliveryPresetFile[];
 }
 
@@ -168,16 +178,18 @@ export async function localStatus(): Promise<{ local: true; workspace: string; s
   return json("/status");
 }
 
-export async function previewDeliveryPreset(provider?: DeliveryProvider): Promise<DeliveryPreset> {
-  const query = provider ? `?provider=${encodeURIComponent(provider)}` : "";
-  return json(`/delivery-presets${query}`);
+export async function previewDeliveryPreset(provider?: DeliveryProvider, features?: DeliveryFeatureId[]): Promise<DeliveryPreset> {
+  const query = new URLSearchParams();
+  if (provider) query.set("provider", provider);
+  if (features) query.set("features", features.join(","));
+  return json(`/delivery-presets${query.size ? `?${query}` : ""}`);
 }
 
-export async function installDeliveryPreset(provider: DeliveryProvider, revision: string): Promise<DeliveryPreset & { written: string[] }> {
+export async function installDeliveryPreset(provider: DeliveryProvider, revision: string, features: DeliveryFeatureId[]): Promise<DeliveryPreset & { written: string[] }> {
   return json("/delivery-presets/install", {
     method: "POST",
     headers: LOCAL_HEADER,
-    body: JSON.stringify({ provider, revision }),
+    body: JSON.stringify({ provider, revision, features }),
   });
 }
 

package/src/lib/motion.test.ts

@@ -102,10 +102,12 @@ describe("presence", () => {
     expect(rise.initial.y).toBe(8);
   });
 
-  it("a page arrives on the page duration and leaves faster, opacity only", () => {
+  it("a page rises in and lifts out faster", () => {
     expect(page.animate.transition).toBe(transitions.page);
     expect(page.exit.transition).toBe(transitions.micro);
-    expect(Object.keys(page.exit)).toEqual(["opacity", "transition"]);
+    expect(page.initial.y).toBe(8);
+    expect(page.animate.y).toBe(0);
+    expect(page.exit.y).toBe(-4);
   });
 
   it("scaleIn grows the two percent palette-in grows", () => {

package/src/lib/motion.tsx

@@ -91,14 +91,15 @@ export const scaleIn: Presence = {
 };
 
 /**
- * A route: rises the eight pixels on the page duration, and leaves on the
- * micro duration, opacity only. The reader has already asked for the next
- * page; the old one should be out of the way, not making an exit.
+ * A route: rises the eight pixels on the page duration while the old page
+ * lifts four pixels and fades on the micro duration. Route presence uses
+ * `popLayout`, so those two short movements overlap instead of inserting a
+ * blank beat between pages.
  */
 export const page: Presence = {
   initial: { opacity: 0, y: 8 },
   animate: { opacity: 1, y: 0, transition: transitions.page },
-  exit: { opacity: 0, transition: transitions.micro },
+  exit: { opacity: 0, y: -4, transition: transitions.micro },
 };
 
 /** A row, a toast: rises the same eight pixels a page rises. */