@shortlink-org/portolan 0.2.1 → 0.2.3

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,
@@ -106,7 +106,7 @@ function AccessForm({
         <button
           type="submit"
           disabled={!draft.trim()}
-          className="btn-accent shrink-0 disabled:opacity-40"
+          className="product-primary shrink-0 disabled:opacity-40"
         >
           {connected ? "Replace token" : "Connect"}
         </button>
@@ -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.