@shortlink-org/portolan 0.2.0 → 0.2.2

package/src/components/MethodRows.tsx

@@ -128,6 +128,7 @@ export function MethodRows({
   open,
   onToggle,
   runs,
+  reference,
 }: {
   provided: RpcService;
   /** Which shapes are expanded, keyed `<interface>/<method>/req|res`. */
@@ -135,6 +136,8 @@ export function MethodRows({
   onToggle: (key: string) => void;
   /** What the method runs, when the page knows — the service page does. */
   runs?: (method: RpcMethod) => ReactNode;
+  /** Protocol-specific tools shown below the method, when its reference has one. */
+  reference?: (method: RpcMethod) => ReactNode;
 }) {
   return (
     <ul data-nav-list>
@@ -227,6 +230,8 @@ export function MethodRows({
 
               {runs?.(method)}
 
+              {reference?.(method)}
+
               {open.has(reqKey) && reqFields ? (
                 <div className="mt-2">
                   <DiscriminatorRows discriminator={reqDiscriminator} />
@@ -240,7 +245,9 @@ export function MethodRows({
                 </div>
               ) : null}
             </div>
-            <RowActions copy={id} />
+            <span className="self-start pt-0.5">
+              <RowActions copy={id} />
+            </span>
           </li>
         );
       })}

package/src/components/PageHeader.test.ts

@@ -0,0 +1,24 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { CapabilityEmpty } from "./PageHeader";
+
+describe("CapabilityEmpty", () => {
+  it("keeps the explanation, action and evidence signal together", () => {
+    const markup = renderToStaticMarkup(createElement(
+      CapabilityEmpty,
+      {
+        title: "No dependency graph yet",
+        actions: createElement("button", { type: "button" }, "Review extraction"),
+        signal: "Signals: domain events and consumers.",
+      },
+      "The catalog has components, but no events to connect.",
+    ));
+
+    expect(markup).toContain("next useful step");
+    expect(markup).toContain("No dependency graph yet");
+    expect(markup).toContain("Review extraction");
+    expect(markup).toContain("Signals: domain events and consumers.");
+  });
+});

package/src/components/PageHeader.tsx

@@ -155,6 +155,40 @@ export function Empty({ children }: { children: ReactNode }) {
   return <div className="empty">{children}</div>;
 }
 
+/**
+ * A page-level absence with a useful next move.
+ *
+ * Unlike `Empty`, this is not the result of a filter, and unlike `Blank` it
+ * does more than document the catalog field that is missing. It is used when
+ * the reader can take a concrete setup action to make the page useful.
+ */
+export function CapabilityEmpty({
+  title,
+  children,
+  actions,
+  signal,
+}: {
+  title: string;
+  children: ReactNode;
+  actions?: ReactNode;
+  /** The source evidence or catalog fact that will fill this page. */
+  signal?: ReactNode;
+}) {
+  return (
+    <div className="rounded-card border border-accent/60 bg-surface p-5 shadow-xs">
+      <div className="label text-accent">next useful step</div>
+      <h2 className="mt-1 text-md font-semibold text-ink">{title}</h2>
+      <div className="mt-2 max-w-prose text-muted">{children}</div>
+      {actions ? <div className="mt-4 flex flex-wrap gap-2">{actions}</div> : null}
+      {signal ? (
+        <div className="mono mt-4 border-t border-line pt-3 text-faint">
+          {signal}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
 /**
  * What a page says before the catalog has anything to put on it.
  *

package/src/components/ShapeRows.tsx

@@ -44,10 +44,13 @@ function EnumRows({ set }: { set: RpcEnum }) {
 export function ShapeRows({
   fields,
   enums,
+  showHeader = false,
 }: {
   fields: Field[];
   /** The interface's enums, so a field typed by one can open its values. */
   enums?: RpcEnum[];
+  /** A contract panel needs named columns; compact inline shapes do not. */
+  showHeader?: boolean;
 }) {
   const [open, setOpen] = useState<Set<string>>(new Set());
   const toggle = (name: string) =>
@@ -60,6 +63,15 @@ export function ShapeRows({
 
   return (
     <table className="w-full">
+      {showHeader ? (
+        <thead>
+          <tr className="label border-b border-line text-left">
+            <th className="pb-1 pr-3 font-normal">Field</th>
+            <th className="pb-1 pr-3 font-normal">Type</th>
+            <th className="pb-1 font-normal">Description</th>
+          </tr>
+        </thead>
+      ) : null}
       <tbody>
         {fields.map((field) => {
           const set = enumFor(enums, field);

package/src/components/SourceDoc.tsx

@@ -20,6 +20,7 @@ import { KindIcon } from "./kind";
 import { MessageList, MethodRows } from "./MethodRows";
 import { paths } from "../routes";
 import { packageOf } from "../lib/registry";
+import { GrpcMethodReference } from "./GrpcMethodReference";
 
 /** The interfaces of one module, as the service page's spec tab shows them. */
 export function ModuleSpec({ moduleId }: { moduleId: string }) {
@@ -46,17 +47,24 @@ export function ModuleSpec({ moduleId }: { moduleId: string }) {
 
   return (
     <div className="max-w-table">
-      <div className="mono flex flex-wrap items-center gap-x-3">
-        <KindIcon kind="module" />
-        <Link
-          to={paths.module(module.slug)}
-          className="text-ink hover:underline"
-        >
-          {module.name}
-        </Link>
-        {module.commit ? (
-          <Ident value={module.commit.slice(0, 12)} className="text-muted" />
-        ) : null}
+      <div className="rounded-card border border-line bg-surface px-4 py-3">
+        <div className="mono flex flex-wrap items-center gap-x-3">
+          <KindIcon kind="module" />
+          <span className="chip">gRPC</span>
+          <Link
+            to={paths.module(module.slug)}
+            className="text-ink hover:underline"
+          >
+            {module.name}
+          </Link>
+          {module.commit ? (
+            <Ident value={module.commit.slice(0, 12)} className="text-muted" />
+          ) : null}
+        </div>
+        <p className="mt-1.5 text-muted">
+          Methods and message shapes extracted from Protocol Buffers. Open a
+          method&apos;s local call to copy a ProtoJSON body or a grpcurl command.
+        </p>
       </div>
 
       {declared.length === 0 ? (
@@ -72,7 +80,14 @@ export function ModuleSpec({ moduleId }: { moduleId: string }) {
             <div className="mono border-b px-3 py-1.5 border-line bg-surface">
               <Ident value={provided.id} className="text-ink" />
             </div>
-            <MethodRows provided={provided} open={open} onToggle={toggle} />
+            <MethodRows
+              provided={provided}
+              open={open}
+              onToggle={toggle}
+              reference={(method) => (
+                <GrpcMethodReference provided={provided} method={method} />
+              )}
+            />
             <MessageList provided={provided} open={open} onToggle={toggle} />
           </div>
         </section>

package/src/components/SourcePreview.tsx

@@ -6,7 +6,7 @@ import {
   Pin,
   X,
 } from "lucide-react";
-import { EditorLink } from "./EditorLink";
+import { EditorLink, useEditorTarget } from "./EditorLink";
 import {
   useCallback,
   useEffect,
@@ -140,7 +140,8 @@ function CodeWindow({
     [file.content, location.line],
   );
   const highlighted = useMemo(
-    () => highlightSource(location.path, rows.map((row) => row.text).join("\n")),
+    () =>
+      highlightSource(location.path, rows.map((row) => row.text).join("\n")),
     [location.path, rows],
   );
   const focusedIndex = rows.findIndex((row) => row.focused);
@@ -149,7 +150,9 @@ function CodeWindow({
     if (node.type === "text") return node.value;
     const names = node.properties?.className;
     const className = Array.isArray(names)
-      ? names.filter((name): name is string => typeof name === "string").join(" ")
+      ? names
+          .filter((name): name is string => typeof name === "string")
+          .join(" ")
       : typeof names === "string"
         ? names
         : undefined;
@@ -187,7 +190,9 @@ function CodeWindow({
           ))}
         </div>
         <pre className="source-code relative z-10 min-w-max pl-3 pr-4 text-ink">
-          <code>{highlighted.map((node, index) => renderNode(node, String(index)))}</code>
+          <code>
+            {highlighted.map((node, index) => renderNode(node, String(index)))}
+          </code>
         </pre>
       </div>
     </div>
@@ -315,18 +320,25 @@ function PreviewPanel({
   );
 }
 
-/** Hover/focus for a glance; click pins the same preview for scrolling and copying. */
-export function SourcePreviewButton({
+function SourcePreviewTrigger({
   location,
+  children,
   className = "",
+  href,
+  external = false,
+  title,
 }: {
-  location: SourceLocation | null;
+  location: SourceLocation;
+  children: ReactNode;
   className?: string;
+  href?: string;
+  external?: boolean;
+  title: string;
 }) {
   const [open, setOpen] = useState(false);
   const [pinned, setPinned] = useState(false);
   const [position, setPosition] = useState<Position | null>(null);
-  const triggerRef = useRef<HTMLButtonElement>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
   const panelRef = useRef<HTMLDivElement>(null);
   const pinnedRef = useRef(false);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -386,41 +398,59 @@ export function SourcePreviewButton({
     return () => document.removeEventListener("pointerdown", outside);
   }, [close, pinned]);
 
-  if (!location) return null;
-
   const hover = (event: ReactPointerEvent) => {
     if (event.pointerType === "mouse" || event.pointerType === "pen")
       openSoon();
   };
 
+  const triggerProps = {
+    "aria-haspopup": "dialog" as const,
+    "aria-expanded": open,
+    "aria-controls": open ? id : undefined,
+    className: `mono inline-flex items-center gap-1 rounded-control text-accent hover:underline focus-visible:outline focus-visible:outline-1 focus-visible:outline-accent ${className}`,
+    title,
+    onPointerEnter: hover,
+    onPointerLeave: closeSoon,
+    onFocus: () => setOpen(true),
+    onBlur: closeSoon,
+  };
+
   return (
     <>
-      <button
-        ref={triggerRef}
-        type="button"
-        aria-haspopup="dialog"
-        aria-expanded={open}
-        aria-controls={open ? id : undefined}
-        className={`mono inline-flex items-center gap-1 rounded-control text-accent hover:underline focus-visible:outline focus-visible:outline-1 focus-visible:outline-accent ${className}`}
-        title="Preview source · click to pin"
-        onPointerEnter={hover}
-        onPointerLeave={closeSoon}
-        onFocus={() => setOpen(true)}
-        onBlur={closeSoon}
-        onClick={() => {
-          cancelTimer();
-          if (open && pinned) {
-            close();
-            return;
-          }
-          setOpen(true);
-          pinnedRef.current = true;
-          setPinned(true);
-          setTimeout(() => panelRef.current?.focus(), 0);
-        }}
-      >
-        <Code2 size={13} aria-hidden /> preview
-      </button>
+      {href ? (
+        <a
+          ref={(node) => {
+            triggerRef.current = node;
+          }}
+          href={href}
+          target={external ? "_blank" : undefined}
+          rel={external ? "noreferrer" : undefined}
+          {...triggerProps}
+        >
+          {children}
+        </a>
+      ) : (
+        <button
+          ref={(node) => {
+            triggerRef.current = node;
+          }}
+          type="button"
+          {...triggerProps}
+          onClick={() => {
+            cancelTimer();
+            if (open && pinned) {
+              close();
+              return;
+            }
+            setOpen(true);
+            pinnedRef.current = true;
+            setPinned(true);
+            setTimeout(() => panelRef.current?.focus(), 0);
+          }}
+        >
+          {children}
+        </button>
+      )}
       {open && position && typeof document !== "undefined"
         ? createPortal(
             <PreviewPanel
@@ -439,3 +469,61 @@ export function SourcePreviewButton({
     </>
   );
 }
+
+/** Hover/focus for a glance; click pins the same preview for scrolling and copying. */
+export function SourcePreviewButton({
+  location,
+  className = "",
+}: {
+  location: SourceLocation | null;
+  className?: string;
+}) {
+  if (!location) return null;
+  return (
+    <SourcePreviewTrigger
+      location={location}
+      className={className}
+      title="Preview source · click to pin"
+    >
+      <Code2 size={13} aria-hidden /> preview
+    </SourcePreviewTrigger>
+  );
+}
+
+/**
+ * A compact source path: preview on hover, then open the configured editor in
+ * local mode or the immutable forge location in a static build.
+ */
+export function SourcePreviewLink({
+  location,
+  children,
+  className = "",
+}: {
+  location: SourceLocation | null;
+  children: ReactNode;
+  className?: string;
+}) {
+  const editor = useEditorTarget(location);
+  if (!location) return <span className={className}>{children}</span>;
+  const href = editor?.href ?? location.href ?? undefined;
+  const destination = editor
+    ? editor.name
+    : location.href
+      ? "repository"
+      : null;
+  return (
+    <SourcePreviewTrigger
+      location={location}
+      className={className}
+      href={href}
+      external={!editor && Boolean(location.href)}
+      title={
+        destination
+          ? `Preview on hover · click to open in ${destination}`
+          : "Preview source · click to pin"
+      }
+    >
+      {children}
+    </SourcePreviewTrigger>
+  );
+}

package/src/enrich.test.ts

@@ -88,7 +88,14 @@ function pricing(): Service {
     provides: [
       {
         id: "pricing.v1.Pricing",
-        methods: [{ name: "Quote", doc: "" }],
+        methods: [
+          {
+            name: "Quote",
+            doc: "",
+            request: "QuoteRequest",
+            response: "QuoteResponse",
+          },
+        ],
         source: "pricing.proto",
       },
     ],
@@ -113,7 +120,7 @@ beforeEach(() => {
 function step(
   from: string,
   to: string,
-  kind: "rpc" | "event" | "call",
+  kind: "rpc" | "event" | "call" | "response",
   extra: Partial<Extract<FlowNode, { type: "step" }>> = {},
 ): FlowNode {
   n += 1;
@@ -287,6 +294,7 @@ describe("enrichCatalog: asynchronous outbound continuations", () => {
       "enqueue void",
       "VoidWorker.Work",
       "POST /cancel",
+      "HTTP response",
     ]);
     expect(root.includes).toEqual(["void-job", "void-http"]);
     expect(once.flows.map((item) => item.slug)).toEqual([
@@ -345,6 +353,7 @@ describe("enrichCatalog: asynchronous outbound continuations", () => {
       "POST /invoices/{id}/issue",
       "enqueue send_invoice_email",
       "send_invoice_email",
+      "HTTP response",
     ]);
     expect(root.includes).toEqual(["send-invoice-email"]);
     expect(enrichCatalog(result).catalog).toEqual(result);
@@ -404,6 +413,127 @@ describe("enrichCatalog: asynchronous outbound continuations", () => {
     expect(enrichCatalog(once).catalog).toEqual(once);
   });
 
+  it("synthesizes returns for nested unary rpc and the HTTP root", () => {
+    const entrypoint = "pricing/rpc:Server.Quote";
+    const api = {
+      ...flow("quote-api", [
+        step("client", "shop.oms", "rpc", { label: "GET /quote" }),
+        step("shop.oms", "shop.pricing", "rpc", {
+          ref: METHOD,
+          label: "Quote",
+          continuesAt: entrypoint,
+        }),
+      ]),
+      trigger: {
+        kind: "http",
+        label: "GET /quote",
+        confidence: "high",
+      } as const,
+    };
+    const provider = {
+      ...flow("quote-rpc", [
+        step("shop.pricing", "shop.pricing", "call", {
+          label: "load quote",
+        }),
+      ]),
+      entrypoint,
+      trigger: {
+        kind: "unproven",
+        label: METHOD,
+        confidence: "high",
+      } as const,
+    };
+
+    const once = enrichCatalog(estate([api, provider])).catalog;
+    const root = once.flows.find((item) => item.slug === "quote-api")!;
+    const steps = walkSteps(root.steps);
+
+    expect(
+      steps.map((item) => [item.kind, item.from, item.to, item.label]),
+    ).toEqual([
+      ["rpc", "client", "shop.oms", "GET /quote"],
+      ["rpc", "shop.oms", "shop.pricing", "Quote"],
+      ["call", "shop.pricing", "shop.pricing", "load quote"],
+      ["response", "shop.pricing", "shop.oms", "QuoteResponse"],
+      ["response", "shop.oms", "client", "HTTP response"],
+    ]);
+    expect(steps[3]!.replyTo).toBe(steps[1]!.id);
+    expect(steps[4]!.replyTo).toBe(steps[0]!.id);
+    expect(enrichCatalog(once).catalog).toEqual(once);
+  });
+
+  it("hydrates a source-proven HTTP body from the serialized rpc response", () => {
+    const api = {
+      ...flow("quote-api", [
+        step("client", "shop.oms", "rpc", { label: "GET /quote" }),
+        step("shop.oms", "shop.pricing", "rpc", {
+          ref: METHOD,
+          label: "Quote",
+        }),
+        step("shop.oms", "client", "response", {
+          label: "200 · HTTP response",
+          replyTo: "s1",
+          http: {
+            status: 200,
+            contentType: "application/json",
+            bodyRef: METHOD,
+            encoding: "protojson",
+            outcome: "success",
+          },
+        }),
+      ]),
+      trigger: {
+        kind: "http",
+        label: "GET /quote",
+        confidence: "high",
+      } as const,
+    };
+
+    const once = enrichCatalog(estate([api])).catalog;
+    const response = walkSteps(once.flows[0]!.steps).at(-1)!;
+
+    expect(response.label).toBe("200 · QuoteResponse");
+    expect(response.http?.body).toBe("QuoteResponse");
+    expect(response.http?.bodyRef).toBe(METHOD);
+    expect(enrichCatalog(once).catalog).toEqual(once);
+  });
+
+  it("does not synthesize a unary return for a streaming rpc", () => {
+    const entrypoint = "pricing/rpc:Server.Watch";
+    const api = {
+      ...flow("watch-api", [
+        step("client", "shop.oms", "rpc", { label: "GET /watch" }),
+        step("shop.oms", "shop.pricing", "rpc", {
+          ref: METHOD,
+          label: "Quote",
+          continuesAt: entrypoint,
+        }),
+      ]),
+      trigger: {
+        kind: "http",
+        label: "GET /watch",
+        confidence: "high",
+      } as const,
+    };
+    const provider = {
+      ...flow("watch-rpc", [
+        step("shop.pricing", "shop.pricing", "call", { label: "watch" }),
+      ]),
+      entrypoint,
+    };
+    const streaming = pricing();
+    streaming.provides[0]!.methods[0]!.streaming = "server";
+
+    const result = enrichCatalog(
+      estate([api, provider], [oms(), streaming]),
+    ).catalog;
+    const responses = walkSteps(result.flows[0]!.steps).filter(
+      (item) => item.kind === "response",
+    );
+
+    expect(responses.map((item) => item.label)).toEqual(["HTTP response"]);
+  });
+
   it("refuses an ambiguous message handoff", () => {
     const publisher = flow("publisher", [
       step("shop.oms", "bus", "event", {
@@ -892,6 +1022,83 @@ describe("enrichCatalog: invariants", () => {
   });
 });
 
+describe("enrichCatalog: Redis store accesses", () => {
+  it("joins a repository call to one concrete Redis key access", () => {
+    const c = estate([
+      flow("load-order", [
+        step("shop.oms", "oms-db", "call", {
+          label: "Get",
+          storeAccess: { store: "shop.oms.redis", method: "Get" },
+        }),
+      ]),
+    ]);
+    c.stores = [
+      {
+        id: "shop.oms.redis",
+        slug: "redis",
+        name: "OMS Redis",
+        kind: "redis",
+        owner: "shop.oms",
+        tables: [],
+        keyspaces: [
+          {
+            pattern: "order:{id}",
+            operations: ["read"],
+            accesses: [
+              {
+                operation: "read",
+                method: "Store.Get",
+                source: "repository/redis.go:20",
+              },
+            ],
+          },
+        ],
+      },
+    ];
+
+    const result = enrichCatalog(c).catalog;
+    expect(walkSteps(result.flows[0]!.steps)[0]!.storeAccess).toEqual({
+      store: "shop.oms.redis",
+      method: "Get",
+      operation: "read",
+      keyspace: "order:{id}",
+      source: "repository/redis.go:20",
+    });
+    expect(enrichCatalog(result).catalog).toBe(result);
+  });
+
+  it("leaves an ambiguous repository method unresolved", () => {
+    const c = estate([
+      flow("load-order", [
+        step("shop.oms", "oms-db", "call", {
+          storeAccess: { store: "shop.oms.redis", method: "Get" },
+        }),
+      ]),
+    ]);
+    c.stores = [
+      {
+        id: "shop.oms.redis",
+        slug: "redis",
+        name: "OMS Redis",
+        kind: "redis",
+        owner: "shop.oms",
+        tables: [],
+        keyspaces: ["order:{id}", "order-by-number:{number}"].map(
+          (pattern) => ({
+            pattern,
+            operations: ["read" as const],
+            accesses: [{ operation: "read" as const, method: "Store.Get" }],
+          }),
+        ),
+      },
+    ];
+
+    expect(
+      walkSteps(enrichCatalog(c).catalog.flows[0]!.steps)[0]!.storeAccess,
+    ).toEqual({ store: "shop.oms.redis", method: "Get" });
+  });
+});
+
 describe("enrichCatalog: the auth fragment", () => {
   // The three fragments together, the way the app reads them: the domain one
   // alone names endpoints the api one declares.