@shortlink-org/portolan 0.2.3 → 0.3.0

package/src/map/ContextMapGraph.tsx

@@ -16,7 +16,14 @@
 // status among everything the line carries: a relationship is known no better
 // than its least-known hop.
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { useNavigate } from "react-router";
 import {
   Background,
@@ -79,6 +86,36 @@ export interface ContextMapGraphProps {
   inactiveNodeOpacity?: number;
 }
 
+// React Flow reads its parent box during mount. The page shell and embedded
+// hero can both briefly be 0×0 while their layout settles, so keep the flow
+// out of that box until a real size has been observed.
+function useMeasuredCanvas() {
+  const canvasRef = useRef<HTMLDivElement>(null);
+  const [hasSize, setHasSize] = useState(false);
+
+  useLayoutEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const measure = (): void => {
+      const next = canvas.clientWidth > 0 && canvas.clientHeight > 0;
+      setHasSize((current) => (current === next ? current : next));
+    };
+
+    measure();
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", measure);
+      return () => window.removeEventListener("resize", measure);
+    }
+
+    const observer = new ResizeObserver(measure);
+    observer.observe(canvas);
+    return () => observer.disconnect();
+  }, []);
+
+  return { canvasRef, hasSize };
+}
+
 export function ContextMapGraph({
   catalog,
   relations,
@@ -97,6 +134,7 @@ export function ContextMapGraph({
     edges: [],
     ready: false,
   });
+  const { canvasRef, hasSize } = useMeasuredCanvas();
 
   // One entry per pair the catalog has anything to say about. `back` is what
   // turns an arrow into a double-headed one; elk only ever sees a -> b, so the
@@ -257,37 +295,43 @@ export function ContextMapGraph({
   );
 
   return (
-    <div className="canvas-motion relative h-full w-full">
-      {drawn.ready ? null : <DiagramSkeleton />}
-      <ReactFlow
-        nodes={shownNodes}
-        edges={shownEdges}
-        nodeTypes={contextNodeTypes}
-        edgeTypes={mapEdgeTypes}
-        onNodeClick={onNodeClick}
-        onNodeDoubleClick={onNodeDoubleClick}
-        onPaneClick={() => clear("diagram")}
-        nodesDraggable={false}
-        nodesConnectable={false}
-        elementsSelectable
-        proOptions={{ hideAttribution: true }}
-        fitView
-        fitViewOptions={{ padding: compactLayout ? 0.06 : 0.16 }}
-        zoomOnScroll={zoomOnScroll}
-        preventScrolling={zoomOnScroll}
-        minZoom={0.2}
-        maxZoom={1.6}
-        key={fitKey}
-      >
-        <Background gap={20} size={2} />
-        {/* The map has no modes to switch, so its only control is the way
-            out: the drawing as a file, for the page that explains it. */}
-        {showExport ? (
-          <Panel position="top-right">
-            <ExportSeg name="context-map" />
-          </Panel>
-        ) : null}
-      </ReactFlow>
+    <div
+      ref={canvasRef}
+      className="canvas-motion relative h-full w-full"
+    >
+      {drawn.ready && hasSize ? (
+        <ReactFlow
+          nodes={shownNodes}
+          edges={shownEdges}
+          nodeTypes={contextNodeTypes}
+          edgeTypes={mapEdgeTypes}
+          onNodeClick={onNodeClick}
+          onNodeDoubleClick={onNodeDoubleClick}
+          onPaneClick={() => clear("diagram")}
+          nodesDraggable={false}
+          nodesConnectable={false}
+          elementsSelectable
+          proOptions={{ hideAttribution: true }}
+          fitView
+          fitViewOptions={{ padding: compactLayout ? 0.06 : 0.16 }}
+          zoomOnScroll={zoomOnScroll}
+          preventScrolling={zoomOnScroll}
+          minZoom={0.2}
+          maxZoom={1.6}
+          key={fitKey}
+        >
+          <Background gap={20} size={2} />
+          {/* The map has no modes to switch, so its only control is the way
+              out: the drawing as a file, for the page that explains it. */}
+          {showExport ? (
+            <Panel position="top-right">
+              <ExportSeg name="context-map" />
+            </Panel>
+          ) : null}
+        </ReactFlow>
+      ) : (
+        <DiagramSkeleton />
+      )}
     </div>
   );
 }

package/src/merge.test.ts

@@ -757,6 +757,29 @@ describe("mergeCatalogs: schema modules", () => {
     // came from.
     expect(channels?.[0]?.source).toBe("bus/asyncapi.yaml");
   });
+
+  it("keeps a message encoding and reports sources that disagree about it", () => {
+    const first = context("shop", ["shop.cart"]);
+    first.services[0]!.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "msgpack", contentType: "application/msgpack" }],
+    }];
+    const second = context("shop", ["shop.cart"]);
+    second.services[0]!.channels = [{
+      address: "shop.cart.basket",
+      messages: [{ name: "cart.BasketCreated", direction: "send", encoding: "json", contentType: "application/json" }],
+    }];
+
+    const merged = mergeCatalogs([
+      source("a-msgpack.json", { contexts: [first] }),
+      source("b-json.json", { contexts: [second] }),
+    ]);
+    const message = merged.catalog.contexts[0]!.services[0]!.channels![0]!.messages[0]!;
+    expect(message.encoding).toBe("msgpack");
+    expect(message.contentType).toBe("application/msgpack");
+    expect(merged.conflicts.map((conflict) => conflict.message).join(" ")).toMatch(/encoding json.*msgpack/);
+    expect(merged.conflicts.map((conflict) => conflict.message).join(" ")).toMatch(/contentType application\/json.*application\/msgpack/);
+  });
 });
 
 describe("a second source that has seen the flow run", () => {

package/src/merge.ts

@@ -42,13 +42,14 @@ import type {
  * A catalog as a FILE may carry it, which is not quite a catalog as a reader
  * gets one: the two stamps are optional here and required downstream.
  *
- * The host stamps what it generates, from the last commit that touched the
- * input the fragment was read from. A file nobody generates - the estate's
- * hand-written facts - is stamped by nobody, and a provenance typed in by hand
- * is a claim no process keeps true: it stays where it was typed while the
- * estate moves on, and being the oldest stamp in the corpus it then dates the
- * whole merged catalog. So a source is allowed to carry no stamp at all, and
- * saying nothing is treated as what it is - an absence of evidence, which
+ * A fragment carries no stamp of its own (portolan.0010). When it last
+ * changed, and in which commit, is what the history of the checkout says,
+ * and whoever reads the file asks the history and hands the answer over
+ * beside it. A file may still say something - a fragment written before
+ * portolan.0010 does - and that is taken only when nobody read the history.
+ * A provenance typed in by hand is a claim no process keeps true, so a source
+ * that says nothing and was read outside any history is stamped by nobody,
+ * and saying nothing is treated as what it is - an absence of evidence, which
  * drops out of the merge rather than voting in it.
  */
 export type SourceCatalog = Omit<Catalog, "generatedAt" | "commit"> &
@@ -59,6 +60,12 @@ export interface CatalogSource {
   /** Where it was read from, as a reader would type it. */
   path: string;
   catalog: SourceCatalog;
+  /**
+   * When the file last changed and in which commit, as the reader found out
+   * from the history of the checkout (portolan.0010). Left out when there
+   * was no history to ask, and the file then speaks for itself.
+   */
+  stamp?: Pick<SourceStamp, "generatedAt" | "commit">;
 }
 
 /**
@@ -120,8 +127,8 @@ export function mergeCatalogs(sources: CatalogSource[]): MergeResult {
 
   const stamps: SourceStamp[] = ordered.map((source) => ({
     path: source.path,
-    generatedAt: source.catalog.generatedAt ?? "",
-    commit: source.catalog.commit ?? "",
+    generatedAt: source.stamp?.generatedAt ?? source.catalog.generatedAt ?? "",
+    commit: source.stamp?.commit ?? source.catalog.commit ?? "",
   }));
 
   for (const { path, catalog } of ordered) {
@@ -442,6 +449,7 @@ function foldMaps(catalog: Catalog, stores: Store[]): Store[] {
       if (!aggregate) return table;
       return {
         ...table,
+        ...(table.accesses ? { accesses: table.accesses.map((access) => ({ ...access })) } : {}),
         columns: table.columns.map((column) => {
           if (!column.maps) return column;
           const maps = fold(aggregate, column.maps);
@@ -608,6 +616,21 @@ function mergeService(
           mine.messages,
           theirs.messages,
           (m) => `${m.direction} ${m.name}`,
+          (held, offered) => {
+            for (const field of ["encoding", "contentType"] as const) {
+              if (!held[field] && offered[field]) {
+                held[field] = offered[field];
+              } else if (held[field] && offered[field] && held[field] !== offered[field]) {
+                conflicts.push({
+                  path,
+                  where: incoming.id,
+                  message: `message "${held.name}" on channel "${mine.address}" of service "${incoming.id}" has ${field} ${offered[field]} here and ${held[field]} in ${owner}; the first one is used`,
+                });
+              }
+            }
+
+            return undefined;
+          },
         );
 
         // Mutated in place: the channel that was here keeps its prose and its
@@ -620,7 +643,7 @@ function mergeService(
 }
 
 function copyChannel(channel: Channel): Channel {
-  return { ...channel, messages: [...channel.messages] };
+  return { ...channel, messages: channel.messages.map((message) => ({ ...message })) };
 }
 
 /**

package/src/pages/AggregatePage.tsx

@@ -77,14 +77,14 @@ function BuildingBlocks({
       </div>
       <div className="flex flex-wrap items-center gap-x-4 gap-y-2 px-4 py-3">
         <span className="mono flex items-center gap-1.5 text-muted">
-          root
+          {aggregate.kind === "model-group" ? "aggregate boundary" : "root"}
           <KindIcon kind="entity" />
           {rootTo ? (
             <Link to={rootTo} className="text-ink hover:underline">
               {aggregate.root}
             </Link>
           ) : (
-            <span className="text-ink">{aggregate.root}</span>
+            <span className="text-ink">{aggregate.kind === "model-group" ? "not specified" : aggregate.root}</span>
           )}
         </span>
         <span aria-hidden className="h-4 w-px bg-line-strong" />
@@ -385,7 +385,7 @@ export function AggregatePage() {
       <PageHeader
         kind={
           <>
-            aggregate ·{" "}
+            {aggregate.kind === "model-group" ? "model group" : "aggregate"} ·{" "}
             <Link
               to={paths.service(context.id, service.slug)}
               className="rounded-control hover:text-ink hover:underline"
@@ -410,6 +410,7 @@ export function AggregatePage() {
           />
 
           <Markdown mermaid>{aggregate.readme}</Markdown>
+          {aggregate.kind === "model-group" ? <p className="mb-section text-muted">Models discovered in this application. Their relationships are extracted from the source; aggregate boundaries have not been specified.</p> : null}
 
           <div
             className="mt-section max-w-prose"
@@ -583,14 +584,14 @@ export function AggregatePage() {
                 anchor={AGGREGATE_ANCHOR.commands}
                 right={
                   <span>
-                    they change the aggregate — one row lock each
+                    {aggregate.kind === "model-group" ? "write operations discovered in this application" : "they change the aggregate — one row lock each"}
                   </span>
                 }
               >
                 Commands
               </SectionTitle>
               {commands.length === 0 ? (
-                <Empty>nothing changes this aggregate from outside</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application commands discovered" : "nothing changes this aggregate from outside"}</Empty>
               ) : null}
               <OperationList kind="command" operations={commands} service={service} />
             </div>
@@ -606,7 +607,7 @@ export function AggregatePage() {
                 Queries
               </SectionTitle>
               {queries.length === 0 ? (
-                <Empty>nothing reads this aggregate by name</Empty>
+                <Empty>{aggregate.kind === "model-group" ? "no application queries discovered" : "nothing reads this aggregate by name"}</Empty>
               ) : null}
               <OperationList kind="query" operations={queries} service={service} />
             </div>
@@ -750,7 +751,7 @@ export function AggregatePage() {
           />
         </div>
 
-        <Toc items={toc} label="Sections of this aggregate" title="Outline" />
+        <Toc items={toc} label={aggregate.kind === "model-group" ? "Sections of this model group" : "Sections of this aggregate"} title="Outline" />
       </div>
     </div>
   );

package/src/pages/CatalogFailure.tsx

@@ -26,8 +26,8 @@ const HINTS: { test: RegExp; hint: string }[] = [
     hint: "A step names a lane the flow never declared. Add the service to the flow's `participants`, or point the step at one that is already there.",
   },
   {
-    test: /resolves to neither an Event nor an RpcCall/,
-    hint: "Either the ref is stale — the event was renamed or removed — or the step really does point at something outside the catalog, in which case its status belongs as `unresolved`.",
+    test: /resolves to neither an Event, an RpcCall nor a method/,
+    hint: "Either the ref is stale — the event or RPC method was renamed or removed — or the step really does point at something outside the catalog, in which case its status belongs as `unresolved`.",
   },
   {
     test: /must have id/,

package/src/pages/ContextPage.tsx

@@ -37,6 +37,7 @@ export function ContextPage() {
   );
   const neutral = groupKind(context) !== "bounded-context";
   const showDomain = !neutral || aggregates.length > 0;
+  const hasModelGroups = aggregates.some(({ aggregate }) => aggregate.kind === "model-group");
   const toc: TocItem[] = [
     { id: CONTEXT_ANCHOR.services, label: neutral ? "Components" : "Services" },
     ...(showDomain
@@ -86,7 +87,7 @@ export function ContextPage() {
           {showDomain ? (
             <>
               <a href={`#${CONTEXT_ANCHOR.aggregates}`} className="rounded-control hover:text-ink">
-                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, "aggregate")}
+                <span className="tnum">{stats.aggregates}</span>{" "}{plural(stats.aggregates, hasModelGroups ? "group" : "aggregate")}
               </a>
               <a href={`#${CONTEXT_ANCHOR.events}`} className="rounded-control hover:text-ink">
                 <span className="tnum">{stats.events}</span>{" "}{plural(stats.events, "event")}
@@ -173,7 +174,7 @@ export function ContextPage() {
                   <div className="mono mt-4 flex flex-wrap gap-x-4 text-muted">
                     {service.aggregates.length > 0 || componentKind(service) === "service" ? (
                       <Link to={`${paths.service(context.id, service.slug)}#svc-aggregates`} className="rounded-control hover:text-ink">
-                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, "aggregate")}
+                        <span className="tnum">{service.aggregates.length}</span>{" "}{plural(service.aggregates.length, service.aggregates.some((aggregate) => aggregate.kind === "model-group") ? "group" : "aggregate")}
                       </Link>
                     ) : null}
                     <Link
@@ -234,11 +235,11 @@ export function ContextPage() {
               anchor={CONTEXT_ANCHOR.aggregates}
               right={
                 <span>
-                  every aggregate this domain owns, whichever service holds it
+                  {hasModelGroups ? "models grouped by their source application or aggregate" : "every aggregate this domain owns, whichever service holds it"}
                 </span>
               }
             >
-              Aggregates
+              {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
             </SectionTitle>
             {aggregates.length === 0 ? (
               <Empty>this domain owns nothing yet — only services</Empty>
@@ -264,7 +265,7 @@ export function ContextPage() {
                       {aggregate.name}
                     </Link>
                     <span className="meta">{service.slug}</span>
-                    <span className="meta">root {aggregate.root}</span>
+                    <span className="meta">{aggregate.kind === "model-group" ? "model group · boundary not specified" : `root ${aggregate.root}`}</span>
                     <RowActions
                       copy={aggregate.id}
                       reveal={aggregate.id}

package/src/pages/ServicePage.tsx

@@ -130,6 +130,7 @@ export function ServicePage() {
     .find((source) => source !== undefined && hasAsyncSpec(source));
   const showDomain =
     componentKind(service) === "service" || service.aggregates.length > 0;
+  const hasModelGroups = service.aggregates.some((aggregate) => aggregate.kind === "model-group");
   const integrations = integrationsFor(service, catalog);
 
   const counts: Record<Tab, number | null> = {
@@ -219,7 +220,7 @@ export function ServicePage() {
               className="rounded-control hover:text-ink"
             >
               <span className="tnum">{service.aggregates.length}</span>{" "}
-              {plural(service.aggregates.length, "aggregate")}
+              {plural(service.aggregates.length, hasModelGroups ? "group" : "aggregate")}
             </a>
           ) : null}
           {showDomain ? (
@@ -312,7 +313,7 @@ export function ServicePage() {
                 className="mt-section max-w-table"
               >
                 <SectionTitle anchor={SERVICE_ANCHOR.aggregates}>
-                  Aggregates
+                  {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
                 </SectionTitle>
                 {/* icon, slug, name, event count, actions - one column each,
                   so the counts stack up instead of drifting with the name. */}
@@ -336,7 +337,7 @@ export function ServicePage() {
                         >
                           {aggregate.slug}
                         </Link>
-                        <span className="meta">{aggregate.name}</span>
+                        <span className="meta">{aggregate.name}{aggregate.kind === "model-group" ? " · model group" : ""}</span>
                         <Link
                           to={`${to}#bb-events`}
                           className="mono rounded-control hover:underline"