@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/flow/trace-trial-resume.ts

@@ -0,0 +1,74 @@
+// A recording's trial, remembered across a reload.
+//
+// Keeping a recording writes portolan.json and then regenerates the catalog,
+// and each of those reloads the page in development - the manifest and the
+// sources are imported, not fetched. The runs go on in the server, which
+// keeps every run's events and replays them to whoever asks; what is lost is
+// the dialog watching them. So the page writes down which run it was
+// watching, and the dialog picks the run back up when the page comes back.
+
+export interface TraceTrialMemory {
+  /** The trial run the dialog was opened on. */
+  runId: string;
+  /** The write run started by keeping the recording, once there is one. */
+  writeRunId: string | null;
+}
+
+/** The storage this reads and writes: sessionStorage in the browser, anything shaped like it in a test. */
+export interface TrialStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+const KEY = "portolan.trace-trial.v1";
+
+/**
+ * `scope` says which page was watching: a flow's slug, or "settings". A
+ * memory left by one page is not picked up by another - a dialog that pops
+ * up on a page the reader did not open it on is a surprise, not a resume.
+ */
+export function rememberTraceTrial(
+  storage: TrialStorage | null,
+  scope: string,
+  memory: TraceTrialMemory,
+): void {
+  try {
+    storage?.setItem(KEY, JSON.stringify({ scope, ...memory }));
+  } catch {
+    // Storage full or forbidden: the dialog simply does not survive a reload.
+  }
+}
+
+export function recallTraceTrial(
+  storage: TrialStorage | null,
+  scope: string,
+): TraceTrialMemory | null {
+  try {
+    const raw = storage?.getItem(KEY);
+    if (!raw) return null;
+    const value = JSON.parse(raw) as Partial<TraceTrialMemory> & { scope?: unknown };
+    if (value.scope !== scope || typeof value.runId !== "string" || !value.runId) return null;
+
+    return { runId: value.runId, writeRunId: typeof value.writeRunId === "string" ? value.writeRunId : null };
+  } catch {
+    return null;
+  }
+}
+
+export function forgetTraceTrial(storage: TrialStorage | null): void {
+  try {
+    storage?.removeItem(KEY);
+  } catch {
+    // Nothing to forget, or nowhere to forget it from.
+  }
+}
+
+/** The browser's session storage, or null where there is none. */
+export function sessionStore(): TrialStorage | null {
+  try {
+    return typeof sessionStorage === "undefined" ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}

package/src/graph/elk.ts

@@ -190,6 +190,84 @@ export async function layoutWithElk(input: LayoutInput): Promise<LayoutResult> {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Groups of nodes, packed
+// ---------------------------------------------------------------------------
+
+export interface GroupLayoutInput {
+  groups: {
+    id: string;
+    nodes: { id: string; width: number; height: number }[];
+    /** Edges between this group's own nodes; one across groups is not laid out. */
+    edges: { id: string; source: string; target: string }[];
+  }[];
+  /** Width over height the packed whole should come out near: the canvas's. */
+  aspectRatio: number;
+  layerSpacing?: number;
+  nodeSpacing?: number;
+  /** Room between two groups' frames. */
+  groupSpacing?: number;
+  /** Room a frame keeps above its nodes, for its label. */
+  labelHeight?: number;
+}
+
+export interface GroupLayoutResult {
+  /** Every node, in the coordinates of the whole picture. */
+  positions: Record<string, Point>;
+  /** Each group's frame, in the same coordinates. */
+  frames: Record<string, { x: number; y: number; width: number; height: number }>;
+  width: number;
+  height: number;
+}
+
+/**
+ * A layered layout inside each group and the groups packed as rectangles
+ * outside, to an aspect ratio. This is for a graph that a single layered pass
+ * cannot draw: one with a layer of fifty nodes, which comes out as a column
+ * whatever direction it is read in. Packing ignores the edges between
+ * groups, deliberately - the caller draws those itself, and a packing that
+ * tried to shorten them would trade the readable shape for it.
+ */
+export async function layoutGroupsWithElk(input: GroupLayoutInput): Promise<GroupLayoutResult> {
+  const labelHeight = input.labelHeight ?? 28;
+  const graph: ElkNode = {
+    id: "root",
+    layoutOptions: {
+      "elk.algorithm": "rectpacking",
+      "elk.aspectRatio": String(input.aspectRatio),
+      "elk.spacing.nodeNode": String(input.groupSpacing ?? 40),
+      "elk.padding": "[top=16,left=16,bottom=16,right=16]",
+    },
+    children: input.groups.map((group) => ({
+      id: group.id,
+      layoutOptions: {
+        "elk.algorithm": "layered",
+        "elk.direction": "RIGHT",
+        "elk.layered.spacing.nodeNodeBetweenLayers": String(input.layerSpacing ?? 120),
+        "elk.spacing.nodeNode": String(input.nodeSpacing ?? 24),
+        "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
+        "elk.padding": `[top=${labelHeight},left=12,bottom=12,right=12]`,
+      },
+      children: group.nodes.map((n) => ({ id: n.id, width: n.width, height: n.height })),
+      edges: group.edges.map((e) => ({ id: e.id, sources: [e.source], targets: [e.target] })),
+    })),
+    edges: [],
+  };
+
+  const laid = await elk.layout(graph);
+  const positions: Record<string, Point> = {};
+  const frames: GroupLayoutResult["frames"] = {};
+  for (const group of laid.children ?? []) {
+    const gx = group.x ?? 0;
+    const gy = group.y ?? 0;
+    frames[group.id] = { x: gx, y: gy, width: group.width ?? 0, height: group.height ?? 0 };
+    for (const child of group.children ?? []) {
+      positions[child.id] = { x: gx + (child.x ?? 0), y: gy + (child.y ?? 0) };
+    }
+  }
+  return { positions, frames, width: laid.width ?? 0, height: laid.height ?? 0 };
+}
+
 // ---------------------------------------------------------------------------
 // Drawing what elk answered
 // ---------------------------------------------------------------------------

package/src/index.css

@@ -51,6 +51,12 @@
   --status-declared: #8a6d1f;
   --status-unresolved: #c02a29;
 
+  /* Which way a message travels on a channel: out is the accent's blue, in
+     is teal, far enough apart that a row reads at a glance and neither is a
+     status colour. */
+  --dir-send: #2563a8;
+  --dir-receive: #0f7a6c;
+
   /* Domain events are the loudest leaf in the tree. Amber, but a step darker
      than amber-600 so 12px mono still clears contrast on white. */
   --kind-event: #b45309;
@@ -173,6 +179,9 @@
   --status-declared: #d6a844;
   --status-unresolved: #ff6b63;
 
+  --dir-send: #82b4f4;
+  --dir-receive: #5fcbb3;
+
   --kind-event: #e8a33d;
   --response-error: #d98288;
   --response-error-bg: #2a1c20;
@@ -428,6 +437,16 @@
     border-color: var(--status-unresolved);
   }
 
+  /* A message's direction on a channel, worn by the chip that names it. */
+  .dir-send {
+    color: var(--dir-send);
+    border-color: var(--dir-send);
+  }
+  .dir-receive {
+    color: var(--dir-receive);
+    border-color: var(--dir-receive);
+  }
+
   /* Section label above a block of content. */
   .label {
     @apply mono uppercase text-muted;
@@ -1485,6 +1504,11 @@
     color: var(--fg-faint);
     background: var(--surface-2);
   }
+  /* A rule on the value - "≥ 1 chars", "matches ^[A-Z]{3}$" - in the same
+     tone. A pattern can run long; the tooltip carries the whole of it. */
+  .rule-mark {
+    @apply max-w-[18ch] truncate;
+  }
 }
 
 /* ---------------------------------------------------------------------------

package/src/landing/LandingPage.tsx

@@ -20,6 +20,7 @@ import { useTheme } from "../app/theme";
 import { useDocumentTitle } from "../app/title";
 import { catalog } from "../data";
 import { m } from "../lib/motion";
+import { landingInputs } from "../lib/plugins";
 import { paths } from "../routes";
 import { catalogTo } from "./catalog";
 import { DraggableReveal } from "./DraggableReveal";
@@ -76,6 +77,9 @@ function Header() {
           <a className="hover:text-ink" href="#get-started">
             Get started
           </a>
+          <Link className="hover:text-ink" to={pluginsTo}>
+            Plugins
+          </Link>
         </nav>
         <div className="ml-auto flex items-center gap-2">
           <button
@@ -146,11 +150,10 @@ function HeroDemo() {
   );
 }
 
-const inputGroups = [
-  { label: "code", items: ["Go", "TypeScript", "Java", "Rust", "Django"] },
-  { label: "contracts", items: ["OpenAPI", "GraphQL", "Protobuf"] },
-  { label: "runtime + data", items: ["SQL", "OTel"] },
-];
+// What the plugins say they read, from the index `npm run schema` writes: a
+// new extractor lands here without anyone remembering to add it.
+const inputGroups = landingInputs();
+const pluginsTo = catalogTo(paths.plugins());
 
 const features = [
   {
@@ -335,14 +338,12 @@ export function LandingPage() {
           <div className="mx-auto flex max-w-[1200px] flex-col gap-5 px-5 py-7 sm:px-8 lg:flex-row lg:items-center">
             <div className="shrink-0">
               <div className="mono text-faint">BUILT-IN INPUTS</div>
-              <a
-                href={`${PRODUCT_REPOSITORY}#plugins`}
-                target="_blank"
-                rel="noreferrer"
+              <Link
+                to={pluginsTo}
                 className="mt-1 inline-flex items-center gap-1 text-sm text-accent hover:underline"
               >
-                See every extractor <ArrowRight size={12} />
-              </a>
+                See every plugin <ArrowRight size={12} />
+              </Link>
             </div>
             <div className="flex flex-wrap gap-x-7 gap-y-3 lg:ml-auto lg:justify-end">
               {inputGroups.map((group) => (
@@ -687,6 +688,9 @@ export function LandingPage() {
             <a className="hover:text-ink" href={PRODUCT_README}>
               Docs
             </a>
+            <Link className="hover:text-ink" to={pluginsTo}>
+              Plugins
+            </Link>
             <a
               className="hover:text-ink"
               href={PRODUCT_LICENSE}

package/src/landing/ProductTour.tsx

@@ -2,7 +2,7 @@
 // product's own canvases in a smaller box; the other two are read straight
 // out of the same catalog. Nothing on this page is drawn from a mock-up.
 
-import { lazy, Suspense, useMemo, useState } from "react";
+import { lazy, Suspense, useState } from "react";
 import { Link } from "react-router";
 import {
   AlertTriangle,
@@ -14,10 +14,10 @@ import {
   Network,
   Radio,
 } from "lucide-react";
-import { catalog, index } from "../data";
+import { index } from "../data";
 import { DiagramSkeleton } from "../components/DiagramSkeleton";
 import { contextVar } from "../lib/context-color";
-import { allProblems } from "../lib/all-problems";
+import { useProblems } from "../lib/use-problems";
 import {
   AnimatePresence,
   LayoutGroup,
@@ -194,7 +194,7 @@ function ContractDemo() {
 const SHOWN_PROBLEMS = 4;
 
 function ProblemsDemo() {
-  const all = useMemo(() => allProblems(catalog, index), []);
+  const all = useProblems();
   const errors = all.filter((p) => p.severity === "error").length;
   const shown = all.slice(0, SHOWN_PROBLEMS);
 
@@ -228,7 +228,7 @@ function ProblemsDemo() {
         <div className="space-y-2">
           {shown.map((problem, i) => (
             <div
-              key={`${problem.kind}:${problem.id}:${problem.peer}`}
+              key={`${problem.rule}:${problem.id}:${problem.peer}`}
               style={staggerStyle(i)}
               className="stagger-in grid grid-cols-[20px_minmax(0,1fr)_auto] items-start gap-3 rounded-card border border-line bg-canvas p-3"
             >
@@ -255,7 +255,7 @@ function ProblemsDemo() {
                 </div>
               </div>
               <span className="chip border-line text-muted">
-                {problem.kind}
+                {problem.rule}
               </span>
             </div>
           ))}

package/src/lib/all-problems.ts

@@ -1,26 +1,36 @@
 // Every reading the catalog makes of itself, in one list.
 //
-// Four readers, each answering a different question: edges that resolve to
-// nothing, producer and consumer schemas that disagree, tables and columns
-// that disagree with the model, and channels that documents and events do not
-// agree on. The problems page, the overview and the landing all want the
-// union, errors first - a boundary leak is not the same kind of news as a
-// column whose type has drifted, and mixing them buries the first.
+// The rules in force - the shipped ones, switched and re-graded as the
+// manifest says, and the estate's own - run over the merged catalog, and
+// what they find comes out as problems. The problems page, the overview and
+// the landing all want the union, errors first - a boundary leak is not the
+// same kind of news as a column whose type has drifted, and mixing them
+// buries the first.
 
 import type { Catalog, CatalogIndex } from "../catalog";
-import { dataProblems } from "./data-problems";
-import { problems } from "./derive";
 import type { Problem } from "./derive";
-import { protoProblems } from "./proto-problems";
-import { wireProblems } from "./wire-problems";
+import { currentRuleEntries, evaluateRules, resolveRules } from "./problem-rules";
+import type { ProblemRule, RuleEvaluation } from "./problem-rules";
 
-export function allProblems(catalog: Catalog, index: CatalogIndex): Problem[] {
-  const found = [
-    ...problems(catalog),
-    ...protoProblems(catalog, index),
-    ...dataProblems(catalog, index),
-    ...wireProblems(catalog, index),
-  ];
+/** The rules over the catalog, with what they had to say about it. */
+export function evaluateProblems(
+  catalog: Catalog,
+  index: CatalogIndex,
+  rules: readonly ProblemRule[] = resolveRules(currentRuleEntries()),
+): RuleEvaluation {
+  const evaluation = evaluateRules(catalog, index, rules);
+  return { ...evaluation, problems: bySeverity(evaluation.problems) };
+}
+
+export function allProblems(
+  catalog: Catalog,
+  index: CatalogIndex,
+  rules: readonly ProblemRule[] = resolveRules(currentRuleEntries()),
+): Problem[] {
+  return evaluateProblems(catalog, index, rules).problems;
+}
+
+function bySeverity(found: Problem[]): Problem[] {
   return [
     ...found.filter((p) => p.severity === "error"),
     ...found.filter((p) => p.severity === "warning"),

package/src/lib/centrality.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Service } from "../catalog";
+import { catalog } from "../testing/estate";
+import { BROKER_SHARE, bridges, centrality, serviceGraph } from "./centrality";
+
+// A catalog reduced to what the graph reads: contexts, services and the
+// calls between them. `a -> b` is a call from a to b; the graph does not
+// care which way, only that the two are joined.
+function estate(
+  contexts: Record<string, string[]>,
+  edges: string[],
+  consumers: Record<string, string[]> = {},
+): Catalog {
+  const service = (context: string, slug: string): Service => {
+    const id = `${context}.${slug}`;
+    return {
+      id,
+      slug,
+      name: slug,
+      repo: "",
+      path: "",
+      readme: "",
+      provides: [],
+      consumes: edges
+        .filter((e) => e.startsWith(`${id} -> `))
+        .map((e) => ({
+          id: `rpc/${e}`,
+          peer: e.slice(id.length + 4),
+          status: "verified" as const,
+          source: "test",
+        })),
+      aggregates:
+        consumers[id] === undefined
+          ? []
+          : [
+              {
+                id: `${id}.root`,
+                slug: "root",
+                name: "root",
+                readme: "",
+                root: "root",
+                entities: [],
+                valueObjects: [],
+                operations: [],
+                events: [
+                  {
+                    id: `${id}.root.Happened`,
+                    slug: "happened",
+                    name: "Happened",
+                    versions: [],
+                    consumers: (consumers[id] ?? []).map((s) => ({
+                      service: s,
+                      status: "verified" as const,
+                    })),
+                  },
+                ],
+              },
+            ],
+    };
+  };
+  return {
+    generatedAt: "2026-01-01T00:00:00Z",
+    commit: "0000000",
+    contexts: Object.entries(contexts).map(([id, slugs]) => ({
+      id,
+      slug: id,
+      name: id,
+      summary: "",
+      services: slugs.map((slug) => service(id, slug)),
+    })),
+    defs: {},
+    flows: [],
+    adrs: [],
+  };
+}
+
+const by = <T extends { id: string }>(list: T[], id: string): T =>
+  list.find((c) => c.id === id) ?? expect.fail(`no ${id}`);
+
+describe("serviceGraph", () => {
+  it("joins a pair once whatever joins them, and both ways", () => {
+    const graph = serviceGraph(
+      estate({ a: ["x", "y"] }, ["a.x -> a.y", "a.y -> a.x"], {
+        "a.x": ["a.y"],
+      }),
+    );
+    expect(graph.adjacent.get("a.x")).toEqual(["a.y"]);
+    expect(graph.adjacent.get("a.y")).toEqual(["a.x"]);
+  });
+
+  it("leaves out ghosts, unresolved peers and a service consuming itself", () => {
+    const graph = serviceGraph(
+      estate({ a: ["x"] }, ["a.x -> fraud-scoring", "a.x -> a.x"], {
+        "a.x": ["analytics-sink", "a.x"],
+      }),
+    );
+    expect(graph.adjacent.get("a.x")).toEqual([]);
+    expect(graph.nodes).toEqual(["a.x"]);
+  });
+});
+
+describe("centrality", () => {
+  it("is zero everywhere on an estate too small to have a middle", () => {
+    const two = centrality(estate({ a: ["x", "y"] }, ["a.x -> a.y"]));
+    expect(two.map((c) => c.betweenness)).toEqual([0, 0]);
+    expect(two.map((c) => c.degree)).toEqual([1, 1]);
+  });
+
+  it("puts the whole of a path through its middle and none through its ends", () => {
+    // x - y - z: the only pair not touching y is none, so y carries 1 of 1.
+    const path = centrality(
+      estate({ a: ["x", "y", "z"] }, ["a.x -> a.y", "a.y -> a.z"]),
+    );
+    expect(by(path, "a.y").betweenness).toBe(1);
+    expect(by(path, "a.x").betweenness).toBe(0);
+    expect(by(path, "a.z").betweenness).toBe(0);
+  });
+
+  it("gives a star's hub everything and its leaves nothing", () => {
+    const star = centrality(
+      estate({ a: ["hub", "p", "q", "r"] }, [
+        "a.p -> a.hub",
+        "a.q -> a.hub",
+        "a.r -> a.hub",
+      ]),
+    );
+    expect(by(star, "a.hub").betweenness).toBe(1);
+    expect(by(star, "a.hub").degree).toBe(3);
+    expect(by(star, "a.p").betweenness).toBe(0);
+  });
+
+  it("splits a pair's paths between two equal roads", () => {
+    // x - y - z and x - w - z: y and w each carry half of the one pair.
+    const square = centrality(
+      estate({ a: ["x", "y", "w", "z"] }, [
+        "a.x -> a.y",
+        "a.x -> a.w",
+        "a.y -> a.z",
+        "a.w -> a.z",
+      ]),
+    );
+    // Three pairs not touching y: (x,z) half through y, (x,w) and (w,z) not.
+    expect(by(square, "a.y").betweenness).toBeCloseTo(0.5 / 3);
+    expect(by(square, "a.w").betweenness).toBeCloseTo(0.5 / 3);
+  });
+
+  it("names the context pairs a service is the road between", () => {
+    // auth.a - shop.gw - shop.core - pay.p: the gateway is the only road
+    // from auth to shop and to pay; core is the only road to pay from both.
+    const c = centrality(
+      estate({ auth: ["a"], shop: ["gw", "core"], pay: ["p"] }, [
+        "auth.a -> shop.gw",
+        "shop.gw -> shop.core",
+        "shop.core -> pay.p",
+      ]),
+    );
+    expect(by(c, "shop.gw").between).toEqual([
+      { a: "auth", b: "shop", share: 1 },
+      { a: "auth", b: "pay", share: 1 },
+    ]);
+    expect(by(c, "shop.core").between).toEqual([
+      { a: "auth", b: "pay", share: 1 },
+      { a: "shop", b: "pay", share: 1 },
+    ]);
+    expect(by(c, "auth.a").between).toEqual([]);
+    expect(by(c, "pay.p").between).toEqual([]);
+  });
+
+  it("does not call a service the road between two contexts when there is another as good", () => {
+    // auth.a reaches pay.p through shop.x or shop.y: each carries exactly
+    // half, and half is not more than half, so neither stands between.
+    const even = centrality(
+      estate({ auth: ["a"], shop: ["x", "y"], pay: ["p"] }, [
+        "auth.a -> shop.x",
+        "auth.a -> shop.y",
+        "shop.x -> pay.p",
+        "shop.y -> pay.p",
+      ]),
+    );
+    expect(by(even, "shop.x").between).toEqual([]);
+    expect(by(even, "shop.y").between).toEqual([]);
+    expect(by(even, "shop.x").betweenness).toBeGreaterThan(0);
+    // A second auth service that reaches pay only through x tilts it: x now
+    // carries (1 + 0.5) of the 2 pairs, y carries 0.5 of them.
+    const tilted = centrality(
+      estate({ auth: ["a1", "a2"], shop: ["x", "y"], pay: ["p"] }, [
+        "auth.a1 -> shop.x",
+        "auth.a1 -> shop.y",
+        "auth.a2 -> shop.x",
+        "shop.x -> pay.p",
+        "shop.y -> pay.p",
+      ]),
+    );
+    expect(by(tilted, "shop.x").between).toEqual([
+      { a: "auth", b: "pay", share: 0.75 },
+    ]);
+    expect(by(tilted, "shop.y").between).toEqual([]);
+    expect(BROKER_SHARE).toBe(0.5);
+  });
+
+  it("does not count the roads a service is at the end of as roads it is between", () => {
+    // auth.a - shop.gw - shop.core: (a, gw) is a road gw is ON. Between
+    // auth and shop, gw carries the one remaining pair (a, core) in full.
+    const c = centrality(
+      estate({ auth: ["a"], shop: ["gw", "core"] }, [
+        "auth.a -> shop.gw",
+        "shop.gw -> shop.core",
+      ]),
+    );
+    expect(by(c, "shop.gw").between).toEqual([{ a: "auth", b: "shop", share: 1 }]);
+  });
+});
+
+describe("bridges", () => {
+  it("lists the estate's roads between contexts, widest first", () => {
+    // In the frozen estate auth reaches everything through cart, and cart
+    // reaches everything but auth through pricing; oms is the only way from
+    // shop and auth into payments and delivery.
+    const list = bridges(catalog);
+    expect(list.map((b) => b.id)).toEqual([
+      "shop.oms",
+      "shop.pricing",
+      "shop.cart",
+    ]);
+    expect(by(list, "shop.cart").between).toEqual([
+      { a: "shop", b: "auth", share: 1 },
+      { a: "payments", b: "auth", share: 1 },
+      { a: "delivery", b: "auth", share: 1 },
+    ]);
+    expect(by(list, "shop.oms").between.map((p) => `${p.a}~${p.b}`)).toEqual([
+      "shop~payments",
+      "shop~delivery",
+      "payments~auth",
+      "delivery~auth",
+    ]);
+    for (const b of list) {
+      expect(b.betweenness).toBeGreaterThan(0);
+      expect(b.betweenness).toBeLessThanOrEqual(1);
+    }
+    expect(list.map((b) => b.betweenness)).toEqual(
+      [...list.map((b) => b.betweenness)].sort((x, y) => y - x),
+    );
+  });
+
+  it("leaves a leaf out however many neighbours it has", () => {
+    const star = bridges(
+      estate({ a: ["hub"], b: ["p"], c: ["q"] }, ["b.p -> a.hub", "c.q -> a.hub"]),
+    );
+    expect(star.map((b) => b.id)).toEqual(["a.hub"]);
+  });
+});