@shortlink-org/portolan 0.2.0 → 0.2.2

package/src/enrich.ts

@@ -59,7 +59,9 @@ export function enrichCatalog(input: Catalog): Enriched {
   // everything below - and every consumer derived from it - sees the event
   // rather than the name.
   const catalog = resolveForeignKeys(
-    composeExecutionContinuations(resolveWireNames(input)),
+    resolveStoreAccesses(
+      composeExecutionContinuations(resolveWireNames(input)),
+    ),
   );
 
   const serviceById = new Map<string, Service>();
@@ -226,6 +228,80 @@ export function enrichCatalog(input: Catalog): Enriched {
   return { catalog: { ...catalog, contexts }, derived };
 }
 
+/**
+ * Joins the use-case-side repository call emitted by extract-go to the
+ * concrete Redis client call emitted independently by extract-redis. Method
+ * name and store id are deliberately both required; a name such as `Get`
+ * alone is far too common to be evidence. Ambiguous matches stay unresolved.
+ */
+function resolveStoreAccesses(input: Catalog): Catalog {
+  const byMethod = new Map<
+    string,
+    Array<{
+      operation: NonNullable<Step["storeAccess"]>["operation"];
+      keyspace: string;
+      source?: string;
+    }>
+  >();
+
+  for (const store of input.stores ?? []) {
+    for (const keyspace of store.keyspaces ?? []) {
+      for (const access of keyspace.accesses ?? []) {
+        if (!access.method) continue;
+        const method = access.method.split(".").pop() ?? access.method;
+        const key = `${store.id}\u0000${method}`;
+        const matches = byMethod.get(key) ?? [];
+        matches.push({
+          operation: access.operation,
+          keyspace: keyspace.pattern,
+          ...(access.source ? { source: access.source } : {}),
+        });
+        byMethod.set(key, matches);
+      }
+    }
+  }
+
+  let changed = false;
+  const mapNodes = (nodes: FlowNode[]): FlowNode[] =>
+    nodes.map((node): FlowNode => {
+      if (node.type === "step") {
+        const storeAccess = node.storeAccess;
+        if (
+          !storeAccess ||
+          !storeAccess.method ||
+          (storeAccess.operation && storeAccess.keyspace)
+        ) {
+          return node;
+        }
+        const method = storeAccess.method.split(".").pop() ?? storeAccess.method;
+        const matches = byMethod.get(`${storeAccess.store}\u0000${method}`) ?? [];
+        if (matches.length !== 1) return node;
+        changed = true;
+        return {
+          ...node,
+          storeAccess: { ...storeAccess, ...matches[0] },
+        };
+      }
+      if (node.type === "alt") {
+        const branches = node.branches.map((branch) => ({
+          ...branch,
+          steps: mapNodes(branch.steps),
+        }));
+        return { ...node, branches };
+      }
+      if (node.type === "parallel") {
+        return { ...node, branches: node.branches.map(mapNodes) };
+      }
+      return { ...node, steps: mapNodes(node.steps) };
+    });
+
+  const flows = input.flows.map((flow) => ({
+    ...flow,
+    steps: mapNodes(flow.steps),
+  }));
+  return changed ? { ...input, flows } : input;
+}
+
 /**
  * Composes independently extracted protocol fragments into root-oriented
  * execution flows.
@@ -237,6 +313,7 @@ export function enrichCatalog(input: Catalog): Enriched {
  * participate. Ambiguous seams compose nothing.
  */
 function composeExecutionContinuations(input: Catalog): Catalog {
+  const responses = synchronousResponses(input);
   const byEntry = new Map<string, Flow | null>();
   const byHandoff = new Map<string, Flow | null>();
   for (const flow of input.flows) {
@@ -259,10 +336,6 @@ function composeExecutionContinuations(input: Catalog): Catalog {
       });
     }
   }
-  if (byEntry.size === 0 && byHandoff.size === 0) {
-    return input;
-  }
-
   const consumed = new Set<string>();
   let any = false;
   const flows = input.flows.map((flow) => {
@@ -275,8 +348,27 @@ function composeExecutionContinuations(input: Catalog): Catalog {
       byEntry,
       byHandoff,
       consumed,
+      responses,
     );
-    if (expansion.includes.length === 0) return flow;
+    let steps = expansion.nodes;
+    const opening = walkSteps(steps)[0];
+    if (
+      flow.trigger?.kind === "http" &&
+      opening?.kind === "rpc" &&
+      !hasResponseFor(steps, opening.id)
+    ) {
+      steps = appendResponseAtExits(
+        steps,
+        responseStep(
+          opening,
+          responses.get(opening.ref ?? "")?.label || "HTTP response",
+          "HTTP handler return",
+        ),
+      );
+    }
+    steps = hydrateHTTPResponseContracts(steps, responses);
+    if (expansion.includes.length === 0 && steps === expansion.nodes)
+      return flow;
     any = true;
 
     const participants = [...flow.participants];
@@ -295,7 +387,7 @@ function composeExecutionContinuations(input: Catalog): Catalog {
         " Source-backed cross-protocol continuations are included.",
       includes: unique([...(flow.includes ?? []), ...expansion.includes]),
       participants,
-      steps: expansion.nodes,
+      steps,
     };
   });
 
@@ -324,6 +416,7 @@ function expandExecution(
   byEntry: ReadonlyMap<string, Flow | null>,
   byHandoff: ReadonlyMap<string, Flow | null>,
   consumed: Set<string>,
+  responses: ReadonlyMap<string, SynchronousResponse>,
 ): ExecutionExpansion {
   const out: FlowNode[] = [];
   const includes: string[] = [];
@@ -333,12 +426,15 @@ function expandExecution(
       case "step": {
         out.push(node);
         if (path.length > 12) break;
-        for (const continuation of continuationsFor(
+        let continuationNodes: FlowNode[] = [];
+        let synchronous = false;
+        for (const continuationMatch of continuationsFor(
           root,
           node,
           byEntry,
           byHandoff,
         )) {
+          const continuation = continuationMatch.flow;
           if (
             path.includes(continuation.slug) ||
             existing.has(continuation.slug)
@@ -354,9 +450,11 @@ function expandExecution(
             byEntry,
             byHandoff,
             consumed,
+            responses,
           );
           const prefix = `continuation-${continuation.slug}-${node.id}`;
-          out.push(...prefixFlowNodes(nested.nodes, prefix));
+          continuationNodes.push(...prefixFlowNodes(nested.nodes, prefix));
+          synchronous ||= continuationMatch.synchronous;
           includes.push(
             continuation.slug,
             ...(continuation.includes ?? []),
@@ -370,6 +468,19 @@ function expandExecution(
             consumed.add(continuation.slug);
           }
         }
+        const response = responses.get(node.ref ?? "");
+        if (
+          synchronous &&
+          node.kind === "rpc" &&
+          response &&
+          !hasResponseFor(nodes, node.id)
+        ) {
+          continuationNodes = appendResponseAtExits(
+            continuationNodes,
+            responseStep(node, response.label, "unary gRPC return"),
+          );
+        }
+        out.push(...continuationNodes);
         break;
       }
       case "alt":
@@ -383,6 +494,7 @@ function expandExecution(
               byEntry,
               byHandoff,
               consumed,
+              responses,
             );
             includes.push(...expanded.includes);
             fragments.push(...expanded.fragments);
@@ -405,6 +517,7 @@ function expandExecution(
               byEntry,
               byHandoff,
               consumed,
+              responses,
             );
             includes.push(...expanded.includes);
             fragments.push(...expanded.fragments);
@@ -426,6 +539,7 @@ function expandExecution(
             byEntry,
             byHandoff,
             consumed,
+            responses,
           );
           includes.push(...expanded.includes);
           fragments.push(...expanded.fragments);
@@ -444,26 +558,36 @@ function expandExecution(
   };
 }
 
+interface ContinuationMatch {
+  flow: Flow;
+  synchronous: boolean;
+}
+
 function continuationsFor(
   root: Flow,
   step: Step,
   byEntry: ReadonlyMap<string, Flow | null>,
   byHandoff: ReadonlyMap<string, Flow | null>,
-): Flow[] {
-  const found: Flow[] = [];
+): ContinuationMatch[] {
+  const found: ContinuationMatch[] = [];
   const sourceEntries = [step.continuesAt, ...(step.reaches ?? [])].filter(
     (entry): entry is string => Boolean(entry),
   );
   for (const entry of sourceEntries) {
     const continuation = byEntry.get(entry);
     if (!continuation || continuation.owner !== root.owner) continue;
-    found.push(continuation);
+    found.push({ flow: continuation, synchronous: true });
   }
   if (step.handoff?.direction === "send") {
     const continuation = byHandoff.get(handoffKey(step.handoff));
-    if (continuation) found.push(continuation);
+    if (continuation) found.push({ flow: continuation, synchronous: false });
+  }
+  const matches = new Map<string, ContinuationMatch>();
+  for (const match of found) {
+    const previous = matches.get(match.flow.slug);
+    if (!previous || match.synchronous) matches.set(match.flow.slug, match);
   }
-  return uniqueFlows(found);
+  return [...matches.values()];
 }
 
 function handoffKey(handoff: NonNullable<Step["handoff"]>): string {
@@ -501,7 +625,11 @@ function prefixFlowNodes(nodes: FlowNode[], prefix: string): FlowNode[] {
     const id = `${prefix}-${node.id}`;
     switch (node.type) {
       case "step":
-        return { ...node, id };
+        return {
+          ...node,
+          id,
+          ...(node.replyTo ? { replyTo: `${prefix}-${node.replyTo}` } : {}),
+        };
       case "alt":
         return {
           ...node,
@@ -525,6 +653,147 @@ function prefixFlowNodes(nodes: FlowNode[], prefix: string): FlowNode[] {
   });
 }
 
+interface SynchronousResponse {
+  label: string;
+}
+
+/** Resolve a source-proven serialized RPC result to its response message. */
+function hydrateHTTPResponseContracts(
+  nodes: FlowNode[],
+  responses: ReadonlyMap<string, SynchronousResponse>,
+): FlowNode[] {
+  let changed = false;
+  const visit = (list: FlowNode[]): FlowNode[] =>
+    list.map((node): FlowNode => {
+      if (node.type === "step") {
+        if (node.kind !== "response" || !node.http) return node;
+        const contract = node.http.bodyRef
+          ? responses.get(node.http.bodyRef)
+          : undefined;
+        const body =
+          node.http.body ||
+          contract?.label ||
+          node.label?.replace(/^\d{3}\s*·\s*/, "") ||
+          "HTTP response";
+        const label = node.http.status ? `${node.http.status} · ${body}` : body;
+        if (node.http.body === body && node.label === label) return node;
+        changed = true;
+        return { ...node, label, http: { ...node.http, body } };
+      }
+      if (node.type === "alt") {
+        const branches = node.branches.map((branch) => ({
+          ...branch,
+          steps: visit(branch.steps),
+        }));
+        return branches.some(
+          (branch, index) => branch.steps !== node.branches[index]!.steps,
+        )
+          ? { ...node, branches }
+          : node;
+      }
+      if (node.type === "parallel") {
+        const branches = node.branches.map(visit);
+        return branches.some((branch, index) => branch !== node.branches[index])
+          ? { ...node, branches }
+          : node;
+      }
+      const nested = visit(node.steps);
+      return nested === node.steps ? node : { ...node, steps: nested };
+    });
+
+  const hydrated = visit(nodes);
+  return changed ? hydrated : nodes;
+}
+
+/** Unary contract responses keyed by `<interface>/<method>`. */
+function synchronousResponses(
+  catalog: Catalog,
+): Map<string, SynchronousResponse> {
+  const out = new Map<string, SynchronousResponse>();
+  const collect = (provided: Service["provides"][number]): void => {
+    for (const method of provided.methods) {
+      if (method.streaming || !method.response) continue;
+      out.set(`${provided.id}/${method.name}`, { label: method.response });
+    }
+  };
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const provided of service.provides) collect(provided);
+    }
+  }
+  for (const external of catalog.externals ?? []) {
+    for (const provided of external.provides) collect(provided);
+  }
+  return out;
+}
+
+function responseStep(request: Step, label: string, protocol: string): Step {
+  return {
+    type: "step",
+    id: `response-${request.id}`,
+    from: request.to,
+    to: request.from,
+    kind: "response",
+    label,
+    status: request.status,
+    note: `Synthesized from the proven synchronous ${protocol}.`,
+    replyTo: request.id,
+  };
+}
+
+function hasResponseFor(nodes: FlowNode[], requestId: string): boolean {
+  return walkSteps(nodes).some(
+    (step) => step.kind === "response" && step.replyTo === requestId,
+  );
+}
+
+/**
+ * Adds a response to every way a synchronous execution can return. A terminal
+ * alt branch gets its own copy inside the branch; the normal fallthrough gets
+ * the unsuffixed response after the nested fragment.
+ */
+function appendResponseAtExits(nodes: FlowNode[], response: Step): FlowNode[] {
+  let emitted = 0;
+  const nextResponse = (): Step => {
+    emitted += 1;
+    return emitted === 1
+      ? response
+      : { ...response, id: `${response.id}-exit-${emitted}` };
+  };
+
+  const visit = (
+    list: FlowNode[],
+    respondAtEnd: boolean,
+  ): { nodes: FlowNode[]; fallsThrough: boolean } => {
+    let fallsThrough = true;
+    const out = list.map((node): FlowNode => {
+      if (node.type === "step") return node;
+      if (node.type === "parallel") {
+        return {
+          ...node,
+          branches: node.branches.map((branch) => visit(branch, false).nodes),
+        };
+      }
+      if (node.type === "loop") {
+        return { ...node, steps: visit(node.steps, false).nodes };
+      }
+
+      const branches = node.branches.map((branch) => {
+        const nested = visit(branch.steps, Boolean(branch.terminal));
+        return { ...branch, steps: nested.nodes };
+      });
+      if (branches.length > 0 && branches.every((branch) => branch.terminal)) {
+        fallsThrough = false;
+      }
+      return { ...node, branches };
+    });
+    if (respondAtEnd && fallsThrough) out.push(nextResponse());
+    return { nodes: out, fallsThrough };
+  };
+
+  return visit(nodes, true).nodes;
+}
+
 /**
  * Steps that name an event by the name it travels under, resolved to the event
  * that travels under it.

package/src/er/RedisSchema.tsx

@@ -1,6 +1,11 @@
-import type { RedisKeyspace, Store } from "../catalog";
+import { allRepos, type RedisKeyspace, type Store } from "../catalog";
+import { Link } from "react-router";
 import { Ident } from "../components/Ident";
+import { SourcePreviewLink } from "../components/SourcePreview";
+import { catalog, index } from "../data";
 import { plural } from "../lib/format";
+import { sourceLocation } from "../lib/source-link";
+import { aggregatePath } from "../routes";
 
 const OPERATION_TONE: Record<string, string> = {
   read: "text-accent",
@@ -11,7 +16,16 @@ const OPERATION_TONE: Record<string, string> = {
   count: "text-ink",
 };
 
-function KeyspaceCard({ keyspace }: { keyspace: RedisKeyspace }) {
+function KeyspaceCard({
+  keyspace,
+  store,
+}: {
+  keyspace: RedisKeyspace;
+  store: Store;
+}) {
+  const aggregateId = keyspace.persists?.aggregate;
+  const aggregateTo = aggregateId ? aggregatePath(aggregateId) : null;
+  const accesses = keyspace.accesses ?? [];
   return (
     <article className="overflow-hidden rounded-card border border-line bg-canvas shadow-xs">
       <div className="flex flex-wrap items-center gap-2 border-b border-line bg-surface px-3 py-2">
@@ -42,15 +56,78 @@ function KeyspaceCard({ keyspace }: { keyspace: RedisKeyspace }) {
             <dd className="mono text-ink">{keyspace.ttl}</dd>
           </>
         ) : null}
-        {keyspace.source ? (
+        {aggregateId ? (
+          <>
+            <dt className="label">persists</dt>
+            <dd className="min-w-0">
+              {aggregateTo ? (
+                <Link
+                  to={aggregateTo}
+                  className="mono text-accent hover:underline"
+                >
+                  {aggregateId} →
+                </Link>
+              ) : (
+                <Ident value={aggregateId} className="max-w-full text-muted" />
+              )}
+            </dd>
+          </>
+        ) : null}
+        {keyspace.source && accesses.length === 0 ? (
           <>
             <dt className="label">source</dt>
             <dd className="min-w-0">
-              <Ident value={keyspace.source} className="max-w-full text-muted" />
+              <Ident
+                value={keyspace.source}
+                className="max-w-full text-muted"
+              />
             </dd>
           </>
         ) : null}
       </dl>
+      {accesses.length > 0 ? (
+        <div className="border-t border-line">
+          <div className="label bg-surface px-3 py-1.5">
+            Accesses · <span className="tnum">{accesses.length}</span>
+          </div>
+          <div className="divide-y divide-line">
+            {accesses.map((access, accessIndex) => {
+              const location = access.source
+                ? sourceLocation(
+                    access.source,
+                    index.serviceById.get(store.owner),
+                    allRepos(catalog),
+                  )
+                : null;
+              return (
+                <div
+                  key={`${access.operation}:${access.method}:${access.source}:${accessIndex}`}
+                  className="grid gap-x-3 gap-y-1 px-3 py-2 sm:grid-cols-[auto_minmax(0,1fr)]"
+                >
+                  <span
+                    className={`chip self-start uppercase ${OPERATION_TONE[access.operation] ?? "text-muted"}`}
+                  >
+                    {access.operation}
+                  </span>
+                  <div className="min-w-0">
+                    <div className="mono break-all text-ink">
+                      {access.method ?? "Redis client call"}
+                    </div>
+                    {access.source ? (
+                      <SourcePreviewLink
+                        location={location}
+                        className="mt-1 max-w-full break-all text-muted hover:text-accent"
+                      >
+                        {access.source}
+                      </SourcePreviewLink>
+                    ) : null}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ) : null}
     </article>
   );
 }
@@ -66,7 +143,11 @@ export function RedisSchema({ store }: { store: Store }) {
       </div>
       <div className="grid gap-3 xl:grid-cols-2">
         {keyspaces.map((keyspace) => (
-          <KeyspaceCard key={keyspace.pattern} keyspace={keyspace} />
+          <KeyspaceCard
+            key={keyspace.pattern}
+            keyspace={keyspace}
+            store={store}
+          />
         ))}
       </div>
     </section>

package/src/flow/FlowTable.tsx

@@ -13,6 +13,7 @@ import { flowStepId } from "../selection/model";
 import { DataTable } from "../table/DataTable";
 import type { ColumnSpec } from "../table/types";
 import type { Chapter } from "./chapters";
+import { stepLabel } from "./labels";
 import type { OutlineStep } from "./outline";
 
 interface Row {
@@ -29,7 +30,13 @@ interface Row {
 }
 
 const COLUMNS: ColumnSpec<Row>[] = [
-  { id: "number", header: "#", type: "number", value: (r) => r.number, size: 56 },
+  {
+    id: "number",
+    header: "#",
+    type: "number",
+    value: (r) => r.number,
+    size: 56,
+  },
   {
     id: "step",
     header: "step",
@@ -45,7 +52,14 @@ const COLUMNS: ColumnSpec<Row>[] = [
     value: (r) => r.route,
     size: 300,
   },
-  { id: "kind", header: "kind", type: "text", value: (r) => r.kind, facet: true, size: 96 },
+  {
+    id: "kind",
+    header: "kind",
+    type: "text",
+    value: (r) => r.kind,
+    facet: true,
+    size: 96,
+  },
   {
     id: "status",
     header: "status",
@@ -93,12 +107,13 @@ export function FlowTable({
   const data = useMemo<Row[]>(() => {
     const chapterOf = new Map<string, string>();
     for (const chapter of chapters) {
-      for (const stepId of chapter.stepIds) chapterOf.set(stepId, chapter.title);
+      for (const stepId of chapter.stepIds)
+        chapterOf.set(stepId, chapter.title);
     }
     return rows.map(({ step, number }) => ({
       id: step.id,
       number,
-      step: step.label ?? step.ref ?? step.kind,
+      step: stepLabel(step),
       route: route(step, contextOf),
       kind: step.kind,
       status: step.status,