@shortlink-org/portolan 0.1.0

package/src/lib/wire-problems.ts

@@ -0,0 +1,281 @@
+// Where two services meet on one channel, and where a service's document and
+// its code do not tell the same story about the bus.
+//
+// A channel belongs to the service that publishes on it, the way a store
+// belongs to the service that writes it: a subscriber to `shop.cart.basket`
+// is told, by the name, whose events it is reading and whose schema to vendor.
+// A second publisher on the same channel breaks that promise silently - the
+// subscriber dispatches on the event's name and never notices the message
+// came from somewhere else, until one arrives that it cannot parse.
+//
+// Two sources say what a service puts on the bus, and they are read out of
+// different files by different extractors. The domain says an aggregate raises
+// an event and how it leaves, in `wire`. An AsyncAPI document says the service
+// declares a channel and what travels on it, in `channels`. Neither is the
+// truth on its own - a document is a promise and a wire is what the code does -
+// and where they disagree is a fact worth a row, because one of them is stale.
+//
+// This is the messaging half of `shared-store`. It is done here, over the
+// 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 { Problem } from "./derive";
+
+interface Publisher {
+  service: Service;
+  context: string;
+  /** The events of this service whose wire names the channel. */
+  events: Event[];
+  /** Whether the service's own document declares it sends here. */
+  declared: boolean;
+}
+
+export function wireProblems(
+  catalog: Catalog,
+  index: CatalogIndex,
+): Problem[] {
+  return [
+    ...sharedChannels(catalog),
+    ...documentAgainstCode(catalog),
+    ...unresolvedSubscriptions(catalog, index),
+  ];
+}
+
+/**
+ * Every service that publishes on a channel another service publishes on
+ * too: one row per service per such channel, pointing at the other side.
+ *
+ * Publishing is either of the two claims - an event whose wire names the
+ * channel, or a document declaring a send on it - because both are the service
+ * saying it owns the channel, and a document that says so while the code has
+ * not caught up is the same collision one release earlier.
+ *
+ * A service with several aggregates on one channel is not this: the channel
+ * is still one service's. An event without a wire is skipped, because a
+ * channel nobody named cannot be shared.
+ */
+function sharedChannels(catalog: Catalog): Problem[] {
+  const byChannel = new Map<string, Map<string, Publisher>>();
+
+  const publisher = (
+    channel: string,
+    service: Service,
+    context: string,
+  ): Publisher => {
+    const publishers = byChannel.get(channel) ?? new Map<string, Publisher>();
+    byChannel.set(channel, publishers);
+    const mine = publishers.get(service.id) ?? {
+      service,
+      context,
+      events: [],
+      declared: false,
+    };
+    publishers.set(service.id, mine);
+
+    return mine;
+  };
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const aggregate of service.aggregates) {
+        for (const event of aggregate.events) {
+          const channel = event.wire?.channel;
+          if (!channel) continue;
+          publisher(channel, service, context.id).events.push(event);
+        }
+      }
+
+      for (const channel of service.channels ?? []) {
+        if (channel.kind && channel.kind !== "event") continue;
+        if (!sends(channel.messages)) continue;
+        publisher(channel.address, service, context.id).declared = true;
+      }
+    }
+  }
+
+  const out: Problem[] = [];
+  for (const [channel, publishers] of byChannel) {
+    if (publishers.size < 2) continue;
+    for (const mine of publishers.values()) {
+      for (const theirs of publishers.values()) {
+        if (theirs === mine) continue;
+        const [first] = mine.events;
+        out.push({
+          kind: "shared-channel",
+          // An error, like a second writer in a database: a subscriber vendors
+          // one publisher's schema, and a message from the other is one it
+          // will fail on, not one it will merely misfile.
+          severity: "error",
+          context: mine.context,
+          service: mine.service.id,
+          // The near end is one event when this side has one, so the row leads
+          // to a page; a side known only from its document leads to the
+          // service, which is the only page there is.
+          id: first?.id ?? mine.service.id,
+          peer: theirs.service.id,
+          note: `${mine.service.id} publishes on ${channel}, and so does ${theirs.service.id}: ${claim(theirs, channel)}. A subscriber reads both without being told.`,
+          source: first?.versions[0]?.source ?? sourceOf(mine.service, channel),
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+/** What a publisher is putting on a channel, as the catalog knows it. */
+function claim(publisher: Publisher, channel: string): string {
+  if (publisher.events.length > 0) {
+    return publisher.events.map((e) => e.name).join(", ");
+  }
+
+  const declared = publisher.service.channels?.find(
+    (c) => c.address === channel,
+  );
+
+  return (
+    declared?.messages
+      .filter((m) => m.direction === "send")
+      .map((m) => m.name)
+      .join(", ") ?? "nothing the catalog can name"
+  );
+}
+
+/**
+ * Where a service's document and its own code disagree about the bus.
+ *
+ * Both directions are a warning rather than an error, and for the same reason:
+ * neither claim is wrong on its own. A channel the code publishes on and the
+ * document does not declare is a document that has fallen behind - or an event
+ * going out where nobody agreed it would. A channel the document declares and
+ * no event names is a promise nothing keeps yet.
+ *
+ * A service with no document says nothing here. Silence is not a disagreement,
+ * and a rule that fired on every service without an AsyncAPI file would be a
+ * page of rows about work nobody has started.
+ */
+function documentAgainstCode(catalog: Catalog): Problem[] {
+  const out: Problem[] = [];
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      const channels = service.channels ?? [];
+      const declared = new Set(
+        channels
+          .filter((c) => (!c.kind || c.kind === "event") && sends(c.messages))
+          .map((c) => c.address),
+      );
+      // Channels that only receive say nothing about what the service
+      // sends: a subscription read out of the code is not a document of
+      // the service's publications, and holding the events against it
+      // would report every one of them.
+      if (declared.size === 0) continue;
+      const published = new Map<string, Event>();
+
+      for (const aggregate of service.aggregates) {
+        for (const event of aggregate.events) {
+          const channel = event.wire?.channel;
+          if (!channel) continue;
+          if (!published.has(channel)) published.set(channel, event);
+          if (declared.has(channel)) continue;
+
+          out.push({
+            kind: "channel-undeclared",
+            severity: "warning",
+            context: context.id,
+            service: service.id,
+            id: event.id,
+            peer: channel,
+            note: `${event.name} goes out on ${channel}, which ${service.id} does not declare it sends on. A subscriber reading the document does not know this message exists.`,
+            source: event.versions[0]?.source,
+          });
+        }
+      }
+
+      for (const channel of channels) {
+        if (channel.kind && channel.kind !== "event") continue;
+        if (!sends(channel.messages)) continue;
+        if (published.has(channel.address)) continue;
+
+        out.push({
+          kind: "channel-unpublished",
+          severity: "warning",
+          context: context.id,
+          service: service.id,
+          id: service.id,
+          peer: channel.address,
+          note: `${service.id} declares it sends on ${channel.address}, and no event of it names that channel: ${channel.messages
+            .filter((m) => m.direction === "send")
+            .map((m) => m.name)
+            .join(", ")}.`,
+          source: channel.source,
+        });
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * A message a service listens for that nothing in the estate publishes.
+ *
+ * This is the only edge in the catalog that runs the other way. Everywhere else
+ * the publisher names its consumers and a name that resolves to nobody is the
+ * problem; here the subscriber names a message, and the estate is searched for
+ * whoever puts it on the wire. A subscription that resolves is how two
+ * repositories that never mention each other are found to be joined.
+ */
+function unresolvedSubscriptions(
+  catalog: Catalog,
+  index: CatalogIndex,
+): Problem[] {
+  // Every name anything in the estate puts on the wire. The index knows the
+  // events; a document declaring a send is the other half, and it counts for
+  // the same reason it counts as publishing above - the code may simply not
+  // have caught up with it yet.
+  const published = new Set(index.eventByWireName.keys());
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const channel of service.channels ?? []) {
+        for (const message of channel.messages) {
+          if (message.direction === "send") published.add(message.name);
+        }
+      }
+    }
+  }
+
+  const out: Problem[] = [];
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const channel of service.channels ?? []) {
+        for (const message of channel.messages) {
+          if (message.direction !== "receive") continue;
+          if (published.has(message.name)) continue;
+
+          out.push({
+            kind: "subscription-unresolved",
+            severity: "warning",
+            context: context.id,
+            service: service.id,
+            id: service.id,
+            peer: message.name,
+            note: `${service.id} listens on ${channel.address} for ${message.name}, and nothing in the catalog publishes it. Either the publisher is outside the estate, or the name has drifted.`,
+            source: channel.source,
+          });
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+function sends(messages: { direction: string }[]): boolean {
+  return messages.some((m) => m.direction === "send");
+}
+
+function sourceOf(service: Service, channel: string): string | undefined {
+  return service.channels?.find((c) => c.address === channel)?.source;
+}

package/src/likec4/C4View.tsx

@@ -0,0 +1,55 @@
+import { useCallback } from "react";
+import { InteractiveView } from "./InteractiveView";
+import { catalogIdOf } from "./mapping";
+import { fqn } from "./ids";
+import { viewHasNode } from "./view-index";
+import { useSelectionStore } from "../selection/store";
+
+/**
+ * A declared C4 element view. Same renderer as the flows, same generated
+ * sources — portolan never draws these itself. Clicking a node selects what it
+ * stands for; clicking the canvas clears.
+ */
+export function C4View({
+  viewId,
+  height = 320,
+  controls = false,
+}: {
+  viewId: string;
+  height?: number | string;
+  /** Zoom controls, useful when a whole estate has to fit on a phone. */
+  controls?: boolean;
+}) {
+  const selection = useSelectionStore((s) => s.selection);
+  const source = useSelectionStore((s) => s.source);
+  const select = useSelectionStore((s) => s.select);
+  const clear = useSelectionStore((s) => s.clear);
+
+  const onNode = useCallback(
+    (likec4Id: string) => select(catalogIdOf(likec4Id), "diagram"),
+    [select],
+  );
+  const onCanvas = useCallback(() => clear("diagram"), [clear]);
+
+  // A selection made here is already marked by LikeC4 itself; one made
+  // elsewhere is only marked when this view actually draws it.
+  const marked =
+    selection && source !== "diagram" && viewHasNode(viewId, fqn(selection.id))
+      ? [fqn(selection.id)]
+      : [];
+
+  return (
+    <div
+      className="w-full overflow-hidden rounded-card border border-line bg-canvas shadow-xs"
+      style={{ height }}
+    >
+      <InteractiveView
+        viewId={viewId}
+        controls={controls}
+        highlightNodes={marked}
+        onNode={onNode}
+        onCanvas={onCanvas}
+      />
+    </div>
+  );
+}

package/src/likec4/CanvasBridge.tsx

@@ -0,0 +1,187 @@
+// The one wire between the page and the picture.
+//
+// LikeC4's diagram API is only reachable from inside its own provider, so this
+// component renders as a child of the canvas and does nothing else: it draws
+// no markup, owns no state of its own, and exists so that the rail outside can
+// move the viewport and the toolbar outside can drive the walkthrough without
+// either of them knowing that a state machine is involved.
+//
+// Two directions, and they are deliberately not symmetrical:
+//
+//   page -> canvas   selecting a step brings its arrow into view. During
+//                    playback that becomes a walkthrough step instead, because
+//                    there must only ever be one animator and it is LikeC4's.
+//   canvas -> page   the walkthrough says which step it is on, and the rail
+//                    follows: it highlights, it expands the chapter, it
+//                    scrolls. The rail never leads the walkthrough.
+
+import { useEffect, useImperativeHandle, useRef } from "react";
+import type { RefObject } from "react";
+import { useDiagram, useDiagramContext } from "likec4/react";
+import type { DiagramApi } from "likec4/react";
+import { boundsOf, focusViewport } from "./canvas-viewport";
+import type { Size } from "./canvas-viewport";
+
+/**
+ * LikeC4 brands its ids so that one kind cannot be passed where another is
+ * wanted. Ours are read straight back out of its own view model, so widening a
+ * string into the brand is a formality rather than a claim — and taking the
+ * type off the method keeps the formality honest if the brand ever changes.
+ */
+type EdgeIdArg = Parameters<DiagramApi["centerViewportOnEdge"]>[0];
+type StepPathArg = Parameters<DiagramApi["startWalkthrough"]>[0] & string;
+
+/**
+ * How big the canvas is right now, measured from the DOM rather than read off
+ * React Flow's store.
+ *
+ * The store's width is kept by a ResizeObserver, which fires a frame late —
+ * and selecting a step opens the detail rail, which takes a hundred-odd pixels
+ * off the canvas in the very same commit. Aiming a viewport with the width the
+ * canvas had a moment ago overshoots by exactly that much, which is how "bring
+ * this step into view" ends up putting it a hundred pixels past the edge.
+ */
+function canvasNode(diagram: DiagramApi): HTMLElement | null {
+  const node: unknown = diagram.getContext().xystore.getState().domNode;
+  return node instanceof HTMLElement ? node : null;
+}
+
+function canvasSize(node: HTMLElement): Size | null {
+  const box = node.getBoundingClientRect();
+  return box.width > 0 && box.height > 0
+    ? { width: box.width, height: box.height }
+    : null;
+}
+
+export interface CanvasHandle {
+  /** Begin playback at the first step. */
+  start: () => void;
+  step: (delta: 1 | -1) => void;
+  stop: () => void;
+  /** The escape hatch from readable zoom: show the whole shape. */
+  fit: () => void;
+  /** The canvas element, for whoever wants to draw it to a file. */
+  node: () => HTMLElement | null;
+}
+
+export function CanvasBridge({
+  handle,
+  activeEdgeId,
+  focusEdgeIds,
+  onWalkthroughEdge,
+}: {
+  handle: RefObject<CanvasHandle | null>;
+  /** The edge the page wants in view, or null when it wants nothing. */
+  activeEdgeId: string | null;
+  /** The selected executable path, fitted after its siblings leave. */
+  focusEdgeIds?: readonly string[] | null;
+  /** The edge playback is on, or null when playback is not running. */
+  onWalkthroughEdge: (edgeId: string | null) => void;
+}) {
+  const diagram = useDiagram();
+  /** The last step the page asked the canvas to show, acted on once. */
+  const asked = useRef<string | null>(null);
+  const walkthroughStep = useDiagramContext(
+    (context) => context.activeWalkthrough?.stepId ?? null,
+  );
+
+  useImperativeHandle(
+    handle,
+    () => ({
+      start: () => diagram.startWalkthrough(),
+      step: (delta) => diagram.walkthroughStep(delta > 0 ? "next" : "prev"),
+      stop: () => diagram.stopWalkthrough(),
+      fit: () => diagram.fitDiagram(),
+      node: () => canvasNode(diagram),
+    }),
+    [diagram],
+  );
+
+  useEffect(() => {
+    onWalkthroughEdge(walkthroughStep ? String(walkthroughStep) : null);
+  }, [walkthroughStep, onWalkthroughEdge]);
+
+  useEffect(() => {
+    if (!activeEdgeId) return;
+
+    if (walkthroughStep) {
+      // Playback is running, so the only thing worth acting on is a step the
+      // reader has just ASKED for — and only once.
+      //
+      // Acting on the value itself would deadlock the two of them: playback
+      // advances to step 3 while the page is still pointing at step 2, the
+      // page scrubs it back to 2, playback reports 2, and neither ever gets
+      // to finish. The ref is what tells "the reader picked this" apart from
+      // "this is what the page was already pointing at".
+      if (activeEdgeId === asked.current) return;
+      asked.current = activeEdgeId;
+      if (String(walkthroughStep) !== activeEdgeId) {
+        // A scrub, not a pan: it moves the playhead rather than the camera.
+        diagram.walkthroughStep({ step: activeEdgeId as StepPathArg });
+      }
+      return;
+    }
+    asked.current = activeEdgeId;
+
+    // Computed here rather than handed to `centerViewportOnEdge`, which caps
+    // the zoom at whatever the viewport already had: an arrow wider than the
+    // pane then ends up centred and still half off the screen, which is not
+    // what "bring step 12 into view" was asked for. The API is still the one
+    // moving the viewport; only the destination is ours.
+    const bounds = boundsOf(diagram.findDiagramEdge(activeEdgeId)?.points ?? []);
+    const node = canvasNode(diagram);
+    if (!bounds || !node) {
+      diagram.centerViewportOnEdge(activeEdgeId as EdgeIdArg);
+      return;
+    }
+
+    const aim = (): void => {
+      const canvas = canvasSize(node);
+      if (!canvas) return;
+      diagram.send({
+        type: "xyflow.setViewport",
+        viewport: focusViewport(bounds, canvas),
+      });
+    };
+
+    aim();
+
+    // And again whenever the canvas changes size under it. Selecting a step is
+    // also what opens the detail rail, which takes its width off the canvas a
+    // commit later — so the first aim is at a canvas that is about to stop
+    // existing, and without this correction the step lands just off the edge.
+    // It keeps the step framed through a divider drag too, which is what the
+    // reader dragging the divider while reading a step wants.
+    const observer = new ResizeObserver(aim);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [activeEdgeId, walkthroughStep, diagram]);
+
+  useEffect(() => {
+    if (activeEdgeId || walkthroughStep || !focusEdgeIds?.length) return;
+    const points = focusEdgeIds.flatMap(
+      (edgeId) => diagram.findDiagramEdge(edgeId)?.points ?? [],
+    );
+    const bounds = boundsOf(points);
+    const node = canvasNode(diagram);
+    if (!bounds || !node) return;
+
+    const aim = (): void => {
+      const canvas = canvasSize(node);
+      if (!canvas) return;
+      diagram.send({
+        type: "xyflow.setViewport",
+        viewport: focusViewport(bounds, canvas),
+        duration: 180,
+      });
+    };
+
+    // Let the stylesheet that hides the other branches land before moving the
+    // camera; the geometry is precomputed, but the transition should describe
+    // the picture the reader can already see.
+    const frame = requestAnimationFrame(aim);
+    return () => cancelAnimationFrame(frame);
+  }, [activeEdgeId, walkthroughStep, focusEdgeIds, diagram]);
+
+  return null;
+}