@shortlink-org/portolan 0.2.3 → 0.2.4

package/src/likec4/flow-edges.ts

@@ -3,10 +3,9 @@
 // id across, so the two are paired by position.
 //
 // That is sound because it is the same walk twice: the generator emits steps in
-// the order walkSteps visits them — a step, then each branch of a parallel,
-// then each branch of an alt, then the body of a loop — and the view keeps that
-// order in its edge list. If the two lists ever differ in length the pairing is
-// abandoned rather than guessed at, and the diagram simply stops highlighting.
+// catalog order and this module inserts the same contract-response edges in the
+// same places. If the two lists ever differ in length the pairing is abandoned
+// rather than guessed at, and the diagram simply stops highlighting.
 
 import type { Flow } from "../catalog";
 import { walkSteps } from "../catalog";
@@ -15,13 +14,16 @@ import { hiddenStepIds } from "../flow/cross-context";
 export interface EdgeStepPairing {
   /** LikeC4 edge id -> catalog step id */
   stepOf: Map<string, string>;
-  /** catalog step id -> LikeC4 edge id */
+  /** catalog step id -> its primary LikeC4 edge id */
   edgeOf: Map<string, string>;
+  /** catalog step id -> every edge it draws, including a contract response */
+  edgesOf: Map<string, string[]>;
 }
 
 export const EMPTY_PAIRING: EdgeStepPairing = {
   stepOf: new Map(),
   edgeOf: new Map(),
+  edgesOf: new Map(),
 };
 
 export function pairEdgesToSteps(
@@ -31,13 +33,17 @@ export function pairEdgesToSteps(
   if (edgeIds.length !== stepIds.length) return EMPTY_PAIRING;
   const stepOf = new Map<string, string>();
   const edgeOf = new Map<string, string>();
+  const edgesOf = new Map<string, string[]>();
   edgeIds.forEach((edgeId, i) => {
     const stepId = stepIds[i];
     if (stepId === undefined) return;
     stepOf.set(edgeId, stepId);
-    edgeOf.set(stepId, edgeId);
+    if (!edgeOf.has(stepId)) edgeOf.set(stepId, edgeId);
+    const edges = edgesOf.get(stepId) ?? [];
+    edges.push(edgeId);
+    edgesOf.set(stepId, edges);
   });
-  return { stepOf, edgeOf };
+  return { stepOf, edgeOf, edgesOf };
 }
 
 /**
@@ -87,3 +93,33 @@ export function drawnStepIds(flow: Flow, crossOnly: boolean): string[] {
   const hidden = hiddenStepIds(flow);
   return steps.filter((s) => !hidden.has(s.id)).map((s) => s.id);
 }
+
+/**
+ * One step id per generated edge, including contract responses synthesized by
+ * the LikeC4 generator. Nested RPCs return immediately; the actor request that
+ * opened the flow returns after its final step.
+ */
+export function drawnEdgeStepIds(
+  flow: Flow,
+  crossOnly: boolean,
+  responseStepIds: ReadonlySet<string>,
+): string[] {
+  const steps = walkSteps(flow.steps);
+  const actorIds = new Set(
+    flow.participants.filter((p) => p.kind === "actor").map((p) => p.id),
+  );
+  const deferred = steps.find(
+    (step) =>
+      step.kind === "rpc" &&
+      actorIds.has(step.from) &&
+      responseStepIds.has(step.id),
+  )?.id;
+  const drawn = drawnStepIds(flow, crossOnly);
+  const out: string[] = [];
+  for (const stepId of drawn) {
+    out.push(stepId);
+    if (stepId !== deferred && responseStepIds.has(stepId)) out.push(stepId);
+  }
+  if (deferred && drawn.includes(deferred)) out.push(deferred);
+  return out;
+}

package/src/likec4/view-index.ts

@@ -8,7 +8,9 @@
 import { pickViewBounds } from "likec4/react";
 import { likec4model } from "./generated";
 import type { Flow } from "../catalog";
-import { drawnStepIds, pairEdgesToSteps } from "./flow-edges";
+import { index } from "../data";
+import { flowAnswers } from "../flow/answers";
+import { drawnEdgeStepIds, pairEdgesToSteps } from "./flow-edges";
 import type { EdgeStepPairing } from "./flow-edges";
 import { EMPTY_PAIRING } from "./flow-edges";
 import { flowCrossViewId, flowViewId } from "./ids";
@@ -70,8 +72,12 @@ export function flowPairing(flow: Flow, crossOnly: boolean): EdgeStepPairing {
   const viewId = crossOnly ? flowCrossViewId(flow) : flowViewId(flow);
   const cached = pairings.get(viewId);
   if (cached) return cached;
+  const responseStepIds = new Set(flowAnswers(index, flow).keys());
   const pairing = shapeOf(viewId).edgeIds.length
-    ? pairEdgesToSteps(shapeOf(viewId).edgeIds, drawnStepIds(flow, crossOnly))
+    ? pairEdgesToSteps(
+        shapeOf(viewId).edgeIds,
+        drawnEdgeStepIds(flow, crossOnly, responseStepIds),
+      )
     : EMPTY_PAIRING;
   pairings.set(viewId, pairing);
   return pairing;

package/src/merge.test.ts

@@ -757,6 +757,29 @@ describe("mergeCatalogs: schema modules", () => {
     // came from.
     expect(channels?.[0]?.source).toBe("bus/asyncapi.yaml");
   });
+
+  it("keeps a message encoding and reports sources that disagree about it", () => {
+    const first = context("shop", ["shop.cart"]);
+    first.services[0]!.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "msgpack", contentType: "application/msgpack" }],
+    }];
+    const second = context("shop", ["shop.cart"]);
+    second.services[0]!.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "json", contentType: "application/json" }],
+    }];
+
+    const merged = mergeCatalogs([
+      source("a-msgpack.json", { contexts: [first] }),
+      source("b-json.json", { contexts: [second] }),
+    ]);
+    const message = merged.catalog.contexts[0]!.services[0]!.channels![0]!.messages[0]!;
+    expect(message.encoding).toBe("msgpack");
+    expect(message.contentType).toBe("application/msgpack");
+    expect(merged.conflicts.map((conflict) => conflict.message).join(" ")).toMatch(/encoding json.*msgpack/);
+    expect(merged.conflicts.map((conflict) => conflict.message).join(" ")).toMatch(/contentType application\/json.*application\/msgpack/);
+  });
 });
 
 describe("a second source that has seen the flow run", () => {

package/src/merge.ts

@@ -442,6 +442,7 @@ function foldMaps(catalog: Catalog, stores: Store[]): Store[] {
       if (!aggregate) return table;
       return {
         ...table,
+        ...(table.accesses ? { accesses: table.accesses.map((access) => ({ ...access })) } : {}),
         columns: table.columns.map((column) => {
           if (!column.maps) return column;
           const maps = fold(aggregate, column.maps);
@@ -608,6 +609,21 @@ function mergeService(
           mine.messages,
           theirs.messages,
           (m) => `${m.direction} ${m.name}`,
+          (held, offered) => {
+            for (const field of ["encoding", "contentType"] as const) {
+              if (!held[field] && offered[field]) {
+                held[field] = offered[field];
+              } else if (held[field] && offered[field] && held[field] !== offered[field]) {
+                conflicts.push({
+                  path,
+                  where: incoming.id,
+                  message: `message "${held.name}" on channel "${mine.address}" of service "${incoming.id}" has ${field} ${offered[field]} here and ${held[field]} in ${owner}; the first one is used`,
+                });
+              }
+            }
+
+            return undefined;
+          },
         );
 
         // Mutated in place: the channel that was here keeps its prose and its
@@ -620,7 +636,7 @@ function mergeService(
 }
 
 function copyChannel(channel: Channel): Channel {
-  return { ...channel, messages: [...channel.messages] };
+  return { ...channel, messages: channel.messages.map((message) => ({ ...message })) };
 }
 
 /**

package/src/pages/CatalogFailure.tsx

@@ -26,8 +26,8 @@ const HINTS: { test: RegExp; hint: string }[] = [
     hint: "A step names a lane the flow never declared. Add the service to the flow's `participants`, or point the step at one that is already there.",
   },
   {
-    test: /resolves to neither an Event nor an RpcCall/,
-    hint: "Either the ref is stale — the event was renamed or removed — or the step really does point at something outside the catalog, in which case its status belongs as `unresolved`.",
+    test: /resolves to neither an Event, an RpcCall nor a method/,
+    hint: "Either the ref is stale — the event or RPC method was renamed or removed — or the step really does point at something outside the catalog, in which case its status belongs as `unresolved`.",
   },
   {
     test: /must have id/,

package/src/pages/Settings.tsx

@@ -56,6 +56,7 @@ import { MachineDocs } from "../components/MachineDocs";
 import { DeliverySettings } from "./settings/DeliverySettings";
 import { PreferencesSettings } from "./settings/PreferencesSettings";
 import { AboutSettings } from "./settings/AboutSettings";
+import { IntegrationsSettings } from "./settings/IntegrationsSettings";
 import { CatEmptyState, CatIllustration } from "../components/CatIllustration";
 import { CommitLink } from "../components/CommitLink";
 
@@ -954,6 +955,7 @@ const SETTINGS_LINKS = [
   ["Projects", paths.settingsProjects()],
   ["Pipeline", paths.settingsPipeline()],
   ["Delivery", paths.settingsDelivery()],
+  ["Integrations", paths.settingsIntegrations()],
   ["Preferences", paths.settingsPreferences()],
   ["About", paths.settingsAbout()],
 ] as const;
@@ -1046,6 +1048,10 @@ function OverviewSettings({ local, onGenerate }: { local: boolean; onGenerate: (
           <div className="font-semibold text-ink">Delivery</div>
           <p className="mt-1 text-muted">Install review checks and static catalog publishing for GitHub or GitLab.</p>
         </Link>
+        <Link to={paths.settingsIntegrations()} className="card">
+          <div className="font-semibold text-ink">Integrations</div>
+          <p className="mt-1 text-muted">Connect operational tools such as Kafka UI to the catalog.</p>
+        </Link>
         <Link to={paths.settingsPreferences()} className="card">
           <div className="font-semibold text-ink">Preferences</div>
           <p className="mt-1 text-muted">Theme, row density, source editor and Ask the catalog.</p>
@@ -1112,15 +1118,16 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
   const pathname = useLocation().pathname.replace(/\/$/, "");
   const overview = pathname === paths.settings();
   const about = pathname === paths.settingsAbout();
+  const browserIntegration = pathname === paths.settingsIntegrations();
   return (
     <div className="h-full overflow-y-auto p-gutter">
       <div className="max-w-table">
         <div className="flex flex-wrap items-start justify-between gap-3">
           <div>
             <div className="flex items-center gap-2"><h1 className="text-lg font-semibold">Settings</h1>{local ? <span className="chip status-verified">local mode</span> : null}</div>
-            <p className="mt-1 max-w-prose text-muted">Configure projects, extraction, delivery automation and local preferences. {local ? "This local session can write reviewed changes." : "Build configuration is read-only here."}</p>
+            <p className="mt-1 max-w-prose text-muted">Configure projects, extraction, delivery automation, integrations and local preferences. {local ? "This local session can write reviewed changes." : "Build configuration is read-only here."}</p>
           </div>
-          {local && !overview && !about ? <button type="button" className="product-primary" onClick={onGenerate}><Play size={15} /> Preview generated diff</button> : null}
+          {local && !overview && !about && !browserIntegration ? <button type="button" className="product-primary" onClick={onGenerate}><Play size={15} /> Preview generated diff</button> : null}
         </div>
         <SettingsNav />
         <div className="mt-section">
@@ -1129,12 +1136,13 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
             <Route path="projects" element={<ProjectsSettings local={local} onAdd={onAdd} onRemove={onRemove} />} />
             <Route path="pipeline" element={<PipelineSettings />} />
             <Route path="delivery" element={<section><SectionTitle right={local ? "preview before writing" : "local mode required"}>Delivery presets</SectionTitle><DeliverySettings local={local} /></section>} />
+            <Route path="integrations" element={<IntegrationsSettings />} />
             <Route path="preferences" element={<PreferencesSettings />} />
             <Route path="about" element={<AboutSettings />} />
             <Route path="*" element={<Navigate to={paths.settings()} replace />} />
           </Routes>
         </div>
-        {!about ? <div className="mono mt-section flex items-center gap-2 pb-section text-muted"><Box size={14} aria-hidden />{local ? "Changes are written only after preview; generated files remain reviewable in git." : "Configuration is embedded at build time; changing it requires a new catalog build."}</div> : null}
+        {!about ? <div className="mono mt-section flex items-center gap-2 pb-section text-muted"><Box size={14} aria-hidden />{browserIntegration ? "Integration settings stay in this browser and do not change the generated catalog." : local ? "Changes are written only after preview; generated files remain reviewable in git." : "Configuration is embedded at build time; changing it requires a new catalog build."}</div> : null}
       </div>
     </div>
   );

package/src/pages/settings/IntegrationsSettings.tsx

@@ -0,0 +1,117 @@
+import { ExternalLink, Save, Trash2 } from "lucide-react";
+import { useState } from "react";
+import { SectionTitle } from "../../components/PageHeader";
+import { TechIcon } from "../../components/TechIcon";
+import { normalizeKafkaUiUrl, useKafkaUi } from "../../lib/kafka-ui";
+import { techGlyph } from "../../lib/tech";
+
+const FIELD =
+  "mono w-full rounded-control border border-line bg-canvas px-3 py-2 text-ink outline-none focus:border-accent";
+
+function KafkaUiCard() {
+  const configured = useKafkaUi((state) => state.url);
+  const setUrl = useKafkaUi((state) => state.setUrl);
+  const [draft, setDraft] = useState(configured);
+  const normalized = normalizeKafkaUiUrl(draft);
+  const valid = normalized !== null;
+  const dirty = valid && normalized !== configured;
+  const glyph = techGlyph("Kafka");
+
+  const save = () => {
+    if (normalized === null) return;
+    setUrl(normalized);
+    setDraft(normalized);
+  };
+
+  const remove = () => {
+    setUrl("");
+    setDraft("");
+  };
+
+  return (
+    <section className="rounded-card border border-line bg-canvas p-card shadow-xs">
+      <div className="flex items-start gap-3">
+        <span className="flex size-9 shrink-0 items-center justify-center rounded-control border border-line bg-surface text-ink">
+          {glyph ? <TechIcon glyph={glyph} size={18} /> : null}
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-2">
+            <h2 className="font-semibold text-ink">Kafka UI</h2>
+            <span className={`chip ${configured ? "status-verified" : "text-muted"}`}>
+              {configured ? "configured" : "not configured"}
+            </span>
+          </div>
+          <p className="mt-1 text-muted">
+            Opens catalogued Kafka topics in your Kafbat Kafka UI installation.
+          </p>
+        </div>
+      </div>
+
+      <label className="mt-4 block">
+        <span className="label mb-1.5 block">Kafka UI cluster URL</span>
+        <input
+          type="url"
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && dirty) save();
+          }}
+          placeholder="https://kafka.example/ui/clusters/production"
+          spellCheck={false}
+          autoComplete="off"
+          aria-invalid={!valid}
+          className={`${FIELD} ${valid ? "" : "border-unresolved"}`}
+        />
+      </label>
+      <p className={`mono mt-2 ${valid ? "text-muted" : "text-unresolved"}`}>
+        {valid
+          ? "Use a cluster or topics URL to open the exact topic. A plain installation URL opens Kafka UI itself."
+          : "Enter an http:// or https:// URL."}
+      </p>
+
+      <div className="mt-4 flex flex-wrap items-center gap-2 border-t border-line pt-4">
+        <button
+          type="button"
+          onClick={save}
+          disabled={!dirty}
+          className="product-primary"
+        >
+          <Save size={14} aria-hidden />
+          Save integration
+        </button>
+        {configured ? (
+          <>
+            <a
+              href={configured}
+              target="_blank"
+              rel="noreferrer"
+              className="tbtn px-3 py-1.5 text-ink"
+            >
+              Open Kafka UI
+              <ExternalLink size={14} aria-hidden />
+            </a>
+            <button
+              type="button"
+              onClick={remove}
+              className="tbtn ml-auto px-3 py-1.5 text-unresolved"
+            >
+              <Trash2 size={14} aria-hidden />
+              Remove
+            </button>
+          </>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+export function IntegrationsSettings() {
+  return (
+    <section>
+      <SectionTitle right="stored in this browser">Integrations</SectionTitle>
+      <div className="grid gap-grid lg:grid-cols-2">
+        <KafkaUiCard />
+      </div>
+    </section>
+  );
+}

package/src/routes.test.ts

@@ -169,12 +169,14 @@ describe("routes", () => {
     expect(paths.settingsProjects()).toBe("/settings/projects");
     expect(paths.settingsPipeline()).toBe("/settings/pipeline");
     expect(paths.settingsDelivery()).toBe("/settings/delivery");
+    expect(paths.settingsIntegrations()).toBe("/settings/integrations");
     expect(paths.settingsPreferences()).toBe("/settings/preferences");
     expect(paths.settingsAbout()).toBe("/settings/about");
     for (const path of [
       paths.settingsProjects(),
       paths.settingsPipeline(),
       paths.settingsDelivery(),
+      paths.settingsIntegrations(),
       paths.settingsPreferences(),
       paths.settingsAbout(),
     ]) expect(isRoutable(path)).toBe(true);

package/src/routes.ts

@@ -45,6 +45,7 @@ export const paths = {
   settingsProjects: () => "/settings/projects",
   settingsPipeline: () => "/settings/pipeline",
   settingsDelivery: () => "/settings/delivery",
+  settingsIntegrations: () => "/settings/integrations",
   settingsPreferences: () => "/settings/preferences",
   settingsAbout: () => "/settings/about",
   external: (slug: string) => `/externals/${slug}`,
@@ -375,7 +376,7 @@ const ROUTES: RegExp[] = [
   /^\/language$/,
   /^\/problems$/,
   /^\/changes$/,
-  /^\/settings(?:\/(?:projects|pipeline|delivery|preferences|about))?$/,
+  /^\/settings(?:\/(?:projects|pipeline|delivery|integrations|preferences|about))?$/,
   /^\/externals\/[^/]+$/,
   /^\/map$/,
   /^\/adrs\/[^/]+$/,

package/src/selection/DetailPanel.tsx

@@ -34,7 +34,7 @@ import { stepLabel } from "../flow/labels";
 import { KIND_LABEL } from "../lib/kinds";
 import { eventScope, resolveShape } from "../lib/shape";
 import { stepsInto } from "../lib/backlinks";
-import { treeHref } from "../lib/source-link";
+import { sourceLocation, treeHref } from "../lib/source-link";
 import { walkSteps } from "../catalog";
 import { methodCount } from "../lib/api";
 import {
@@ -49,6 +49,7 @@ import { upstreamOf } from "../er/lineage";
 import type { LineageMaps } from "../er/lineage";
 import { ctxStyle } from "../lib/context-color";
 import { Ident } from "../components/Ident";
+import { SourcePreviewLink } from "../components/SourcePreview";
 import { StatusChip } from "../components/primitives";
 import { StepDetailBody } from "../flow/StepDetail";
 import {
@@ -420,6 +421,50 @@ function TableBody({
         </>
       ) : null}
 
+      {(table.accesses ?? []).length > 0 ? (
+        <>
+          <Label>Reads / writes</Label>
+          {(table.accesses ?? []).map((access, accessIndex) => {
+            const location = access.source
+              ? sourceLocation(
+                  access.source,
+                  index.serviceById.get(store.owner),
+                  allRepos(catalog),
+                )
+              : null;
+            const tone =
+              access.operation === "read"
+                ? "text-accent"
+                : access.operation === "write"
+                  ? "text-verified"
+                  : "text-unresolved";
+            return (
+              <div
+                key={`${access.operation}:${access.method}:${access.source}:${accessIndex}`}
+                className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-2 gap-y-0.5 py-1"
+              >
+                <span className={`chip self-start uppercase ${tone}`}>
+                  {access.operation}
+                </span>
+                <div className="min-w-0">
+                  <div className="mono break-all text-ink">
+                    {access.method ?? "SQL client call"}
+                  </div>
+                  {access.source ? (
+                    <SourcePreviewLink
+                      location={location}
+                      className="mono block break-all text-muted hover:text-accent"
+                    >
+                      {access.source}
+                    </SourcePreviewLink>
+                  ) : null}
+                </div>
+              </div>
+            );
+          })}
+        </>
+      ) : null}
+
       <Label>Referenced by</Label>
       {into.length === 0 ? (
         <div className="mono text-muted">nothing points at this table</div>