@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/components/ChannelRows.tsx

@@ -12,10 +12,15 @@
 // is either a publisher outside the estate or a name that has drifted, and the
 // Problems page says which; a row that quietly dropped it would be the site
 // hiding the interesting case.
+//
+// Direction is the first thing a reader asks of a channel - what goes out, what
+// comes in - so it is drawn, not only written: an arrow and a colour per
+// direction, a filter to keep one, and a grouping that folds the two rows a
+// message has on a work queue (put on, worked) into one.
 
-import { ExternalLink } from "lucide-react";
-import { Link } from "react-router";
-import type { Channel, ChannelMessage } from "../catalog";
+import { ArrowDownLeft, ArrowUpRight, ExternalLink, Layers } from "lucide-react";
+import { Link, useSearchParams } from "react-router";
+import type { Channel, ChannelDirection, ChannelMessage } from "../catalog";
 import { catalog, index } from "../data";
 import {
   isKafkaChannel,
@@ -29,6 +34,8 @@ import { RowActions } from "./RowActions";
 
 const KAFKA_HANDOFF_CHANNELS = kafkaHandoffChannels(catalog);
 
+export type DirectionFilter = "all" | ChannelDirection;
+
 /** The event that goes out under a wire name, when the catalog knows one. */
 function publisherOf(name: string) {
   const event = index.eventByWireName.get(name);
@@ -40,11 +47,41 @@ function publisherOf(name: string) {
   return { event, owner, path };
 }
 
+const DIRECTION = {
+  send: {
+    Icon: ArrowUpRight,
+    className: "chip dir-send",
+    title: "this service puts it on the channel",
+  },
+  receive: {
+    Icon: ArrowDownLeft,
+    className: "chip dir-receive",
+    title: "this service listens for it",
+  },
+} as const;
+
+function DirectionChip({ direction }: { direction: ChannelDirection }) {
+  const { Icon, className, title } = DIRECTION[direction];
+  return (
+    <span className={className} title={title} data-direction={direction}>
+      <Icon size={11} aria-hidden />
+      {direction}
+    </span>
+  );
+}
+
+/**
+ * One row: a message and the directions it travels. Ungrouped, a message that
+ * is both sent and received is two rows with one direction each; grouped, it
+ * is one row wearing both chips.
+ */
 function MessageRow({
   message,
+  directions,
   mine,
 }: {
   message: ChannelMessage;
+  directions: readonly ChannelDirection[];
   /** The service this channel belongs to, so a row can say when the publisher is someone else. */
   mine: string;
 }) {
@@ -58,16 +95,9 @@ function MessageRow({
     <li className="row rounded-none border-x-0 border-t-0 last:border-b-0">
       <div className="min-w-0 flex-1">
         <div className="flex flex-wrap items-center gap-x-2">
-          <span
-            className="chip mono"
-            title={
-              message.direction === "send"
-                ? "this service puts it on the channel"
-                : "this service listens for it"
-            }
-          >
-            {message.direction}
-          </span>
+          {directions.map((direction) => (
+            <DirectionChip key={direction} direction={direction} />
+          ))}
           {published ? (
             <Link
               to={published.path}
@@ -99,6 +129,64 @@ function MessageRow({
   );
 }
 
+/** A message with every direction it travels on the channel, in send-then-receive order. */
+interface MessageGroup {
+  message: ChannelMessage;
+  directions: ChannelDirection[];
+}
+
+/**
+ * The rows a channel shows: one per message and direction, or - grouped - one
+ * per message with both directions, the sent one supplying the doc because it
+ * is what the sender wrote down. A filter keeps one direction; a grouped row
+ * that loses its other half keeps the chip it still has.
+ */
+export function rowsOf(
+  messages: readonly ChannelMessage[],
+  filter: DirectionFilter,
+  grouped: boolean,
+): MessageGroup[] {
+  const kept = messages.filter(
+    (message) => filter === "all" || message.direction === filter,
+  );
+  if (!grouped) {
+    return kept.map((message) => ({ message, directions: [message.direction] }));
+  }
+  const groups: MessageGroup[] = [];
+  for (const message of kept) {
+    const group = groups.find((g) => g.message.name === message.name);
+    if (!group) {
+      groups.push({ message, directions: [message.direction] });
+    } else {
+      if (!group.directions.includes(message.direction)) {
+        group.directions.push(message.direction);
+      }
+      // The sent message carries the sender's doc; a receive found first is
+      // replaced by it, so that a grouped row reads the same either way.
+      if (message.direction === "send" && group.message.direction === "receive") {
+        group.message = message;
+      }
+    }
+  }
+  for (const group of groups) {
+    group.directions.sort((a, b) => (a === b ? 0 : a === "send" ? -1 : 1));
+  }
+  return groups;
+}
+
+/** How many messages travel each way, across every channel. */
+export function countDirections(channels: readonly Channel[]) {
+  let send = 0;
+  let receive = 0;
+  for (const channel of channels) {
+    for (const message of channel.messages) {
+      if (message.direction === "send") send += 1;
+      else receive += 1;
+    }
+  }
+  return { send, receive };
+}
+
 export function ChannelRows({
   channels,
   service,
@@ -107,12 +195,75 @@ export function ChannelRows({
   service: string;
 }) {
   const kafkaUi = useKafkaUi((state) => state.url);
+  // The filter and the grouping live in the URL beside the tab, so that the
+  // view a reader ends up with is the one their link opens.
+  const [params, setParams] = useSearchParams();
+  const dir = params.get("dir");
+  const filter: DirectionFilter =
+    dir === "send" || dir === "receive" ? dir : "all";
+  const grouped = params.get("group") === "message";
+  const set = (key: string, value: string | null) => {
+    const next = new URLSearchParams(params);
+    if (value === null) next.delete(key);
+    else next.set(key, value);
+    setParams(next, { replace: true });
+  };
+  const counts = countDirections(channels);
+
   return (
-    <ChannelRowsContent
-      channels={channels}
-      service={service}
-      kafkaUi={kafkaUi}
-    />
+    <div className="flex flex-col gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="seg bg-canvas" role="group" aria-label="Direction shown">
+          <button
+            type="button"
+            onClick={() => set("dir", null)}
+            aria-pressed={filter === "all"}
+            className={filter === "all" ? "is-on" : ""}
+            title="Every message, both ways"
+          >
+            all <span className="tnum text-muted">{counts.send + counts.receive}</span>
+          </button>
+          <button
+            type="button"
+            onClick={() => set("dir", "send")}
+            aria-pressed={filter === "send"}
+            className={filter === "send" ? "is-on" : ""}
+            title="Only what this service puts on a channel"
+          >
+            <ArrowUpRight size={11} aria-hidden className="inline" /> send{" "}
+            <span className="tnum text-muted">{counts.send}</span>
+          </button>
+          <button
+            type="button"
+            onClick={() => set("dir", "receive")}
+            aria-pressed={filter === "receive"}
+            className={filter === "receive" ? "is-on" : ""}
+            title="Only what this service listens for"
+          >
+            <ArrowDownLeft size={11} aria-hidden className="inline" /> receive{" "}
+            <span className="tnum text-muted">{counts.receive}</span>
+          </button>
+        </div>
+        <div className="seg bg-canvas" role="group" aria-label="Grouping">
+          <button
+            type="button"
+            onClick={() => set("group", grouped ? null : "message")}
+            aria-pressed={grouped}
+            className={grouped ? "is-on" : ""}
+            title="One row per message, with every direction it travels"
+          >
+            <Layers size={11} aria-hidden className="inline" /> by message
+          </button>
+        </div>
+      </div>
+      <ChannelRowsContent
+        channels={channels}
+        service={service}
+        kafkaUi={kafkaUi}
+        filter={filter}
+        grouped={grouped}
+      />
+    </div>
   );
 }
 
@@ -121,59 +272,71 @@ export function ChannelRowsContent({
   channels,
   service,
   kafkaUi,
+  filter = "all",
+  grouped = false,
 }: {
   channels: Channel[];
   service: string;
   kafkaUi: string;
+  filter?: DirectionFilter;
+  grouped?: boolean;
 }) {
   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-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>
+      {channels.map((channel) => {
+        const rows = rowsOf(channel.messages, filter, grouped);
+        return (
+          <div key={channel.address} className="rounded-card border border-line">
+            <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>
-            {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>
+            {channel.doc ? (
+              <p className="px-3 py-2 text-muted">{channel.doc}</p>
             ) : null}
+            {channel.messages.length === 0 ? (
+              <p className="px-3 py-2 text-muted">
+                declared, and no operation says which way it travels
+              </p>
+            ) : rows.length === 0 ? (
+              <p className="px-3 py-2 text-muted">
+                {filter === "send" ? "nothing sent" : "nothing received"}
+              </p>
+            ) : (
+              <ul>
+                {rows.map(({ message, directions }) => (
+                  <MessageRow
+                    key={`${directions.join("+")} ${message.name}`}
+                    message={message}
+                    directions={directions}
+                    mine={service}
+                  />
+                ))}
+              </ul>
+            )}
           </div>
-          {channel.doc ? (
-            <p className="px-3 py-2 text-muted">{channel.doc}</p>
-          ) : null}
-          {channel.messages.length === 0 ? (
-            <p className="px-3 py-2 text-muted">
-              declared, and no operation says which way it travels
-            </p>
-          ) : (
-            <ul>
-              {channel.messages.map((message) => (
-                <MessageRow
-                  key={`${message.direction} ${message.name}`}
-                  message={message}
-                  mine={service}
-                />
-              ))}
-            </ul>
-          )}
-        </div>
-      ))}
+        );
+      })}
     </div>
   );
 }

package/src/components/DeploymentRows.tsx

@@ -0,0 +1,131 @@
+// Where a service runs, one row per Application the deployer lists for it.
+//
+// The environment is the row's identity: it is what a reader scans for -
+// "is it in prod yet" - and what the snapshot groups by. The revision is the
+// answer to the next question, "which commit", and is a link to the commit
+// on the forge when it is one; a chart version is not, and is shown as it
+// is. The application link opens the deployer's own page, which is where
+// health and sync live: they move without a commit and are not kept here.
+
+import { ExternalLink } from "lucide-react";
+import type { Deployment } from "../catalog";
+import { deploymentBasis } from "../catalog";
+import { driftLines } from "../lib/deployment-drift";
+import { Ident } from "./Ident";
+import { RowActions } from "./RowActions";
+
+/** The commit on the forge, when the revision is one and the repository is known. */
+function commitHref(deployment: Deployment): string | null {
+  if (!deployment.repo || !/^[0-9a-f]{40}$/.test(deployment.revision)) {
+    return null;
+  }
+  const repo = `https://${deployment.repo}`;
+  const view = repo.toLowerCase().includes("gitlab") ? "/-/commit/" : "/commit/";
+  return `${repo}${view}${deployment.revision}`;
+}
+
+/** A commit shortened the way `git log --oneline` shortens it; anything else whole. */
+function shortRevision(revision: string): string {
+  return /^[0-9a-f]{40}$/.test(revision) ? revision.slice(0, 7) : revision;
+}
+
+function DeploymentRow({ deployment }: { deployment: Deployment }) {
+  const href = commitHref(deployment);
+  const where = [deployment.cluster, deployment.namespace]
+    .filter(Boolean)
+    .join(" / ");
+  return (
+    <div className="row items-start px-2 py-1.5">
+      <span className="chip" title="the environment the application is placed in">
+        {deployment.environment}
+      </span>
+      <span className="mono text-muted" title="cluster / namespace">
+        {where}
+      </span>
+      <div className="min-w-0">
+        <span className="inline-flex flex-wrap items-center gap-x-2 gap-y-1">
+          {deployment.revision ? (
+            href ? (
+              <a
+                href={href}
+                target="_blank"
+                rel="noreferrer"
+                className="mono text-ink hover:underline"
+                title={`${deployment.revision} on the forge`}
+              >
+                {shortRevision(deployment.revision)}
+              </a>
+            ) : (
+              <Ident value={deployment.revision}>
+                {shortRevision(deployment.revision)}
+              </Ident>
+            )
+          ) : (
+            <span className="text-muted">not synced yet</span>
+          )}
+          {deployment.targetRevision ? (
+            <span className="text-muted" title="what the application tracks">
+              tracks {deployment.targetRevision}
+            </span>
+          ) : null}
+          {deployment.tool ? (
+            <span className="chip mono">{deployment.tool}</span>
+          ) : null}
+          {/* Who said so, when only the tree has: what should run, with
+              nothing yet saying it does. A row both spoke for says nothing
+              here - agreement is the ordinary case and needs no chip. */}
+          {deploymentBasis(deployment) === "manifest" ? (
+            <span
+              className="chip status-declared"
+              title="declared in the GitOps tree; the deployer has not been read for it"
+            >
+              declared
+            </span>
+          ) : null}
+          {/* The tree and the deployer disagree. The chip carries the
+              difference in words, so a reader does not have to open both. */}
+          {driftLines(deployment).length > 0 ? (
+            <span
+              className="chip status-unresolved"
+              title={driftLines(deployment).join("\n")}
+            >
+              drift
+            </span>
+          ) : null}
+        </span>
+        {deployment.images?.length ? (
+          <ul className="mt-0.5 flex flex-wrap gap-x-2 gap-y-0.5">
+            {deployment.images.map((image) => (
+              <li key={image}>
+                <Ident value={image} className="text-muted">
+                  {image}
+                </Ident>
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+      <a
+        href={deployment.url}
+        target="_blank"
+        rel="noreferrer"
+        className="inline-flex items-center gap-1 rounded-control text-accent hover:underline"
+        title={`${deployment.name} in Argo CD, where its health and sync state are`}
+      >
+        {deployment.name}
+        <ExternalLink size={12} aria-hidden />
+      </a>
+      <RowActions copy={deployment.name} label={deployment.name} />
+    </div>
+  );
+}
+
+export function DeploymentRows({ deployments }: { deployments: Deployment[] }) {
+  return (
+    <div className="rows grid-cols-[auto_auto_1fr_auto_auto]">
+      {deployments.map((deployment) => (
+        <DeploymentRow key={deployment.id} deployment={deployment} />
+      ))}
+    </div>
+  );
+}

package/src/components/DocsLinks.test.tsx

@@ -0,0 +1,27 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { DocsLinksContent } from "./DocsLinks";
+
+describe("DocsLinks", () => {
+  it("searches Confluence by name and opens the Notion workspace", () => {
+    const markup = renderToStaticMarkup(
+      <DocsLinksContent
+        name="shop.oms"
+        confluence="https://acme.atlassian.net/wiki/spaces/ARCH"
+        notion="https://www.notion.so/acme"
+      />,
+    );
+    expect(markup).toContain("view in Confluence");
+    expect(markup).toContain(
+      'href="https://acme.atlassian.net/wiki/search?text=shop.oms&amp;spaces=ARCH"',
+    );
+    expect(markup).toContain("open Notion");
+    expect(markup).toContain('href="https://www.notion.so/acme"');
+  });
+
+  it("renders nothing before either integration is configured", () => {
+    expect(
+      renderToStaticMarkup(<DocsLinksContent name="shop.oms" confluence="" notion="" />),
+    ).toBe("");
+  });
+});

package/src/components/DocsLinks.tsx

@@ -0,0 +1,56 @@
+// The hand-off from a page to where its team writes: a Confluence search by
+// name, and the Notion workspace. Nothing until the reader has configured
+// either under Settings → Integrations; the values live in this browser.
+
+import { ExternalLink } from "lucide-react";
+import { confluenceSearchUrl, useConfluence } from "../lib/confluence";
+import { useNotion } from "../lib/notion";
+
+const LINK =
+  "inline-flex items-center gap-1 whitespace-nowrap rounded-control text-accent hover:underline";
+
+export function DocsLinksContent({
+  name,
+  confluence,
+  notion,
+}: {
+  /** What to search for: the service's or context's name. */
+  name: string;
+  confluence: string;
+  notion: string;
+}) {
+  const search = confluenceSearchUrl(confluence, name);
+  if (!search && !notion) return null;
+  return (
+    <>
+      {search ? (
+        <a
+          href={search}
+          target="_blank"
+          rel="noreferrer"
+          className={LINK}
+          title={`Search Confluence for ${name}`}
+        >
+          view in Confluence <ExternalLink size={12} aria-hidden />
+        </a>
+      ) : null}
+      {notion ? (
+        <a
+          href={notion}
+          target="_blank"
+          rel="noreferrer"
+          className={LINK}
+          title="Open the Notion workspace where the documentation lives"
+        >
+          open Notion <ExternalLink size={12} aria-hidden />
+        </a>
+      ) : null}
+    </>
+  );
+}
+
+export function DocsLinks({ name }: { name: string }) {
+  const confluence = useConfluence((state) => state.url);
+  const notion = useNotion((state) => state.url);
+  return <DocsLinksContent name={name} confluence={confluence} notion={notion} />;
+}

package/src/components/FieldTree.tsx

@@ -22,6 +22,7 @@ import type { Scope, Shape } from "../lib/shape";
 import { blockPath, enumPath } from "../routes";
 import { Ident } from "./Ident";
 import { KindIcon } from "./kind";
+import { RuleMarks } from "./RuleMarks";
 
 /** The words the type chip uses for what `parseType` found. */
 const CARDINALITY: Record<"many" | "map", string> = {
@@ -31,8 +32,9 @@ const CARDINALITY: Record<"many" | "map", string> = {
 
 /**
  * The type of a field, as a reader wants it: the raw spelling to copy, a
- * word for the wrapper it is in, and a way to the page of the shape it
- * names. Shared by the table cell and the tree row so both say it the same.
+ * word for the wrapper it is in, what the source says the value must
+ * satisfy, and a way to the page of the shape it names. Shared by the table
+ * cell and the tree row so both say it the same.
  */
 export function TypeCell({
   field,
@@ -70,6 +72,7 @@ export function TypeCell({
           optional
         </span>
       ) : null}
+      <RuleMarks field={field} />
       {page && shape ? (
         <Link
           to={page}

package/src/components/HTTPDestinationEvidence.test.tsx

@@ -0,0 +1,23 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { expect, it } from "vitest";
+import { HTTPDestinationEvidence } from "./HTTPDestinationEvidence";
+
+it("shows the join and the config default behind a resolved destination", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "c.baseURL + path", method: "POST",
+    localPath: "/get-admin-settings", fullPath: "/settings/get-admin-settings",
+    baseURL: { expression: "cfg.SettingAddr", configField: "Config.SettingAddr", environmentVariable: "SETTINGS_ADDR", kind: "config-default", value: "http://localhost:8000/settings", source: "config.go:84", optionSource: "modules_tree.go:212" },
+    join: { expression: "c.baseURL + path", source: "client.go:10" },
+    resolution: { basis: "full-path", provider: "avia.aviaadmin", route: "/settings/get-admin-settings" },
+  }} />);
+  for (const value of ["Recovered full path", "Config default (runtime may override)", "SETTINGS_ADDR", "modules_tree.go:212", "Config.SettingAddr", "/settings/get-admin-settings", "avia.aviaadmin"]) expect(html).toContain(value);
+  expect(html).not.toContain("heuristic");
+});
+
+it("labels suffix resolution as a heuristic", () => {
+  const html = renderToStaticMarkup(<HTTPDestinationEvidence destination={{
+    callSite: "client.go:10", endpointExpression: "/settings", method: "POST",
+    resolution: { basis: "unique-suffix", provider: "admin", route: "/admin/settings" },
+  }} />);
+  expect(html).toContain("Unique route suffix (heuristic)");
+});

package/src/components/HTTPDestinationEvidence.tsx

@@ -0,0 +1,31 @@
+import type { HTTPDestination } from "../catalog";
+
+/** Display the facts for this invocation, including the limits of defaults. */
+export function HTTPDestinationEvidence({ destination: d }: { destination: HTTPDestination }) {
+  const basis = d.resolution?.basis;
+  const rows = [
+    ["Linked by", basis === "full-path" ? "Recovered full path" : basis === "exact-route" ? "Exact route" : basis === "unique-suffix" ? "Unique route suffix (heuristic)" : basis === "kubernetes-host" ? "Kubernetes Service host, from the manifests" : "Unresolved"],
+    ["Call site", d.callSite],
+    ["Endpoint expression", d.endpointExpression],
+    ["Local path", d.localPath],
+    ["Base URL expression", d.baseURL?.expression],
+    ["Config field", d.baseURL?.configField],
+    ["Environment variable", d.baseURL?.environmentVariable],
+    [d.baseURL?.kind === "config-default" ? "Config default (runtime may override)" : "Base URL", d.baseURL?.value],
+    ["Config source", d.baseURL?.source],
+    ["Option call site", d.baseURL?.optionSource],
+    ["Service discovery alias", d.serviceDiscoveryAlias],
+    ["Join expression", d.join?.expression],
+    ["Join source", d.join?.source],
+    ["Full path", d.fullPath],
+    ...(d.transforms ?? []).map((transform) => ["Runtime URL modifier (not evaluated)", `${transform.expression} · ${transform.source}`]),
+    ["Provider", d.resolution?.provider],
+    ["Provider route", d.resolution?.route],
+  ].filter(([, value]) => value);
+  return <section aria-label="HTTP destination evidence" className="border-t border-line px-3 py-3">
+    <h3 className="label mb-2">HTTP destination evidence</h3>
+    <dl className="grid min-w-0 grid-cols-1 gap-y-3">
+      {rows.map(([label, value], index) => <div key={`${label}-${index}`} className="min-w-0"><dt className="text-muted">{label}</dt><dd className="mono break-all text-ink">{value}</dd></div>)}
+    </dl>
+  </section>;
+}

package/src/components/Integrations.tsx

@@ -210,7 +210,7 @@ export function Integrations({ groups }: { groups: IntegrationGroup[] }) {
                         <RowActions copy={call.id} label={call.id} />
                         {method?.http ? (
                           <p className="mono w-full text-muted">
-                            {method.http.method} {method.http.path}
+                            {method.http.method ? `${method.http.method} ${method.http.path}` : method.http.path}
                           </p>
                         ) : null}
                         {call.note ? (