@shortlink-org/portolan 0.2.4 → 0.4.0

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"]);
+  });
+});

package/src/lib/centrality.ts

@@ -0,0 +1,232 @@
+// Which services the estate's paths run through.
+//
+// The dependency graph shows who talks to whom; the context map shows which
+// contexts depend on which. Neither answers a third question a reader asks
+// before touching a service: if this one goes, what stops reaching what? A
+// service with three neighbours can be the only road between two contexts,
+// and a service with twelve can be a leaf of every one of them. Degree does
+// not tell them apart. Betweenness does: the share of shortest paths between
+// every pair of services that pass through this one.
+//
+// The graph is the same two facts the context map is drawn from - an event
+// with a consumer, a call with a peer - collapsed to one undirected edge per
+// pair of services. Undirected, because the question is "who is between",
+// and a reader who asks it means the road, not which way the traffic runs.
+// Unweighted, because a pair joined by one call and a pair joined by twenty
+// are both joined.
+//
+// Two things are counted, and the page says which is which:
+//
+//   betweenness - Brandes' number, normalised so 1 means every shortest path
+//                 between every other pair runs through this service. It ranks.
+//   between     - the pairs of CONTEXTS for which more than half of the
+//                 shortest paths between their services run through this one.
+//                 It is the finding: "auth reaches payments only through cart".
+//
+// Consumers with no service of their own and calls to a peer the catalog does
+// not know are left out. A ghost has no context to be between, and an
+// unresolved peer is a problem the problems page already lists.
+
+import type { Catalog } from "../catalog";
+
+/** A pair of contexts this service stands between. */
+export interface Brokered {
+  /** The two contexts, in catalog order. */
+  a: string;
+  b: string;
+  /** Share of shortest paths between the two that pass through the service. */
+  share: number;
+}
+
+export interface Centrality {
+  id: string;
+  context: string;
+  /** Distinct services it exchanges anything with. */
+  degree: number;
+  /** Normalised to 0..1; 0 on an estate of fewer than three services. */
+  betweenness: number;
+  between: Brokered[];
+}
+
+/**
+ * The share of a context pair's paths a service must carry MORE than to be
+ * said to stand between them. Half, strictly: two equal roads are two roads,
+ * and a service on one of them is not what the other side depends on.
+ */
+export const BROKER_SHARE = 0.5;
+
+export interface ServiceGraph {
+  /** Service ids in catalog order. */
+  nodes: string[];
+  /** Service id -> context id. */
+  context: Map<string, string>;
+  /** Undirected adjacency, neighbours in first-seen order. */
+  adjacent: Map<string, string[]>;
+}
+
+/** One undirected edge per pair of catalog services that exchange anything. */
+export function serviceGraph(catalog: Catalog): ServiceGraph {
+  const nodes: string[] = [];
+  const context = new Map<string, string>();
+  for (const ctx of catalog.contexts) {
+    for (const service of ctx.services) {
+      nodes.push(service.id);
+      context.set(service.id, ctx.id);
+    }
+  }
+
+  const adjacent = new Map<string, string[]>(nodes.map((id) => [id, []]));
+  const join = (a: string, b: string): void => {
+    if (a === b || !context.has(a) || !context.has(b)) return;
+    const ofA = adjacent.get(a) as string[];
+    if (ofA.includes(b)) return;
+    ofA.push(b);
+    (adjacent.get(b) as string[]).push(a);
+  };
+
+  for (const ctx of catalog.contexts) {
+    for (const service of ctx.services) {
+      for (const aggregate of service.aggregates) {
+        for (const event of aggregate.events) {
+          for (const consumer of event.consumers) join(service.id, consumer.service);
+        }
+      }
+      for (const call of service.consumes) join(service.id, call.peer);
+    }
+  }
+  return { nodes, context, adjacent };
+}
+
+/**
+ * Brandes' algorithm, with the dependency of each source split by the target's
+ * context, so the same pass that sums betweenness also says which context
+ * pairs a service carries.
+ */
+export function centrality(catalog: Catalog): Centrality[] {
+  const graph = serviceGraph(catalog);
+  const { nodes, context, adjacent } = graph;
+  const n = nodes.length;
+  const order = catalog.contexts.map((c) => c.id);
+  const rank = new Map(order.map((id, i) => [id, i]));
+
+  const raw = new Map<string, number>(nodes.map((id) => [id, 0]));
+  // node -> (source context ~ target context) -> summed dependency.
+  const carried = new Map<string, Map<string, number>>(
+    nodes.map((id) => [id, new Map()]),
+  );
+  // source -> target context -> reachable targets (the source excluded).
+  const reach = new Map<string, Map<string, number>>();
+
+  for (const s of nodes) {
+    const stack: string[] = [];
+    const pred = new Map<string, string[]>(nodes.map((id) => [id, []]));
+    const sigma = new Map<string, number>(nodes.map((id) => [id, 0]));
+    const dist = new Map<string, number>(nodes.map((id) => [id, -1]));
+    sigma.set(s, 1);
+    dist.set(s, 0);
+    const queue: string[] = [s];
+    for (let head = 0; head < queue.length; head += 1) {
+      const v = queue[head] as string;
+      stack.push(v);
+      const dv = dist.get(v) as number;
+      for (const w of adjacent.get(v) as string[]) {
+        if ((dist.get(w) as number) < 0) {
+          dist.set(w, dv + 1);
+          queue.push(w);
+        }
+        if ((dist.get(w) as number) === dv + 1) {
+          sigma.set(w, (sigma.get(w) as number) + (sigma.get(v) as number));
+          (pred.get(w) as string[]).push(v);
+        }
+      }
+    }
+
+    const seen = new Map<string, number>();
+    for (const t of stack) {
+      if (t === s) continue;
+      const c = context.get(t) as string;
+      seen.set(c, (seen.get(c) ?? 0) + 1);
+    }
+    reach.set(s, seen);
+
+    // delta[w][targetContext]: dependency of s on w, over targets in that context.
+    const delta = new Map<string, Map<string, number>>(
+      nodes.map((id) => [id, new Map()]),
+    );
+    while (stack.length > 0) {
+      const w = stack.pop() as string;
+      const dw = delta.get(w) as Map<string, number>;
+      const own = context.get(w) as string;
+      for (const v of pred.get(w) as string[]) {
+        const ratio = (sigma.get(v) as number) / (sigma.get(w) as number);
+        const dv = delta.get(v) as Map<string, number>;
+        dv.set(own, (dv.get(own) ?? 0) + ratio);
+        for (const [c, d] of dw) dv.set(c, (dv.get(c) ?? 0) + ratio * d);
+      }
+      if (w === s) continue;
+      const from = context.get(s) as string;
+      const bucket = carried.get(w) as Map<string, number>;
+      let sum = 0;
+      for (const [to, d] of dw) {
+        sum += d;
+        const key = pairKey(from, to, rank);
+        bucket.set(key, (bucket.get(key) ?? 0) + d);
+      }
+      raw.set(w, (raw.get(w) as number) + sum);
+    }
+  }
+
+  // Ordered (u, v) pairs with u in A and v in B, both reachable, any u and v.
+  const pairs = (a: string, b: string): number => {
+    let count = 0;
+    for (const s of nodes) {
+      if (context.get(s) !== a) continue;
+      count += reach.get(s)?.get(b) ?? 0;
+    }
+    return count;
+  };
+
+  const scale = n < 3 ? 0 : 2 / ((n - 1) * (n - 2));
+  return nodes.map((id) => {
+    const own = context.get(id) as string;
+    const between: Brokered[] = [];
+    for (const [key, sum] of carried.get(id) as Map<string, number>) {
+      const [a, b] = key.split("~") as [string, string];
+      // Every (u, v) was counted from both ends; and pairs with the service
+      // itself at an end are roads it is on, not roads it is between.
+      let total = a === b ? pairs(a, a) / 2 : pairs(a, b);
+      if (own === a) total -= reach.get(id)?.get(b) ?? 0;
+      else if (own === b) total -= reach.get(id)?.get(a) ?? 0;
+      const share = total > 0 ? sum / 2 / total : 0;
+      if (a !== b && share > BROKER_SHARE) between.push({ a, b, share });
+    }
+    between.sort(
+      (x, y) =>
+        y.share - x.share ||
+        (rank.get(x.a) ?? 0) - (rank.get(y.a) ?? 0) ||
+        (rank.get(x.b) ?? 0) - (rank.get(y.b) ?? 0),
+    );
+    return {
+      id,
+      context: own,
+      degree: (adjacent.get(id) as string[]).length,
+      betweenness: ((raw.get(id) as number) / 2) * scale,
+      between,
+    };
+  });
+}
+
+function pairKey(a: string, b: string, rank: Map<string, number>): string {
+  return (rank.get(a) ?? 0) <= (rank.get(b) ?? 0) ? `${a}~${b}` : `${b}~${a}`;
+}
+
+/**
+ * The services worth a reader's attention: on some shortest path, and the
+ * main road between at least one pair of contexts. Highest betweenness first,
+ * catalog order between equals.
+ */
+export function bridges(catalog: Catalog): Centrality[] {
+  return centrality(catalog)
+    .filter((c) => c.betweenness > 0 && c.between.length > 0)
+    .sort((x, y) => y.betweenness - x.betweenness);
+}

package/src/lib/confluence.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { confluenceSearchUrl } from "./confluence";
+
+describe("Confluence integration", () => {
+  it("searches the whole Cloud site from a site URL", () => {
+    expect(confluenceSearchUrl("https://acme.atlassian.net/wiki", "shop.oms")).toBe(
+      "https://acme.atlassian.net/wiki/search?text=shop.oms",
+    );
+  });
+
+  it("narrows the search to the space a Cloud URL names", () => {
+    expect(
+      confluenceSearchUrl(
+        "https://acme.atlassian.net/wiki/spaces/ARCH/overview",
+        "Order management",
+      ),
+    ).toBe(
+      "https://acme.atlassian.net/wiki/search?text=Order+management&spaces=ARCH",
+    );
+  });
+
+  it("uses the Server search page behind a context path", () => {
+    expect(
+      confluenceSearchUrl("https://wiki.example/confluence/display/ARCH", "shop.oms"),
+    ).toBe(
+      "https://wiki.example/confluence/dosearchsite.action?queryString=shop.oms&where=ARCH",
+    );
+    expect(confluenceSearchUrl("https://wiki.example/", "shop.oms")).toBe(
+      "https://wiki.example/dosearchsite.action?queryString=shop.oms",
+    );
+  });
+
+  it("offers nothing before a URL is configured or when it is unsafe", () => {
+    expect(confluenceSearchUrl("", "shop.oms")).toBeNull();
+    expect(confluenceSearchUrl("javascript:alert(1)", "shop.oms")).toBeNull();
+  });
+});

package/src/lib/confluence.ts

@@ -0,0 +1,41 @@
+// The optional hand-off from a catalogued service or context to the wiki
+// where its team writes.
+//
+// The catalog carries no page ids, so the link is a search by name: the one
+// address Confluence answers for any installation. A site URL searches the
+// whole site; a URL that names a space narrows the search to it. Cloud and
+// Server answer at different paths, told apart by the `/wiki` prefix Cloud
+// always has.
+
+import { createIntegrationStore, normalizeIntegrationUrl } from "./integration-url";
+
+export const CONFLUENCE_KEY = "portolan.integrations.confluence";
+
+/** The search page for `name`, on the site or in the space the URL names. */
+export function confluenceSearchUrl(
+  configured: string,
+  name: string,
+): string | null {
+  const normalized = normalizeIntegrationUrl(configured);
+  if (!normalized) return null;
+  const url = new URL(normalized);
+  const path = url.pathname;
+  const space = path.match(/\/(?:spaces|display)\/([^/]+)/)?.[1];
+  const cloud = path.match(/^(.*\/wiki)(?:\/.*)?$/)?.[1];
+  const params = new URLSearchParams();
+  if (cloud !== undefined) {
+    url.pathname = `${cloud}/search`;
+    params.set("text", name);
+    if (space) params.set("spaces", space);
+  } else {
+    const base = path.replace(/\/(?:spaces|display)\/.*$/, "").replace(/\/$/, "");
+    url.pathname = `${base}/dosearchsite.action`;
+    params.set("queryString", name);
+    if (space) params.set("where", space);
+  }
+  url.search = params.toString();
+  url.hash = "";
+  return url.toString();
+}
+
+export const useConfluence = createIntegrationStore(CONFLUENCE_KEY);

package/src/lib/context-color.ts

@@ -1,7 +1,7 @@
 import type { CSSProperties } from "react";
 import { catalog } from "../data";
 
-const CTX_SLOTS = 6;
+export const CTX_SLOTS = 6;
 
 /** Context colour is assigned deterministically by index in catalog order. */
 const order: string[] = catalog.contexts.map((c) => c.id);

package/src/lib/deployment-drift.ts

@@ -0,0 +1,22 @@
+// The fields the GitOps tree and the deployer disagree on, said in one line
+// each. Read by the deployment rows on a service's page and by the
+// `deployment` subject a rule sees, so the two say the same words.
+
+import type { Deployment } from "../catalog";
+
+export function driftLines(deployment: Deployment): string[] {
+  const drift = deployment.drift;
+  if (!drift) return [];
+  const lines: string[] = [];
+  if (drift.project) lines.push(`project ${drift.project} in the tree, ${deployment.project} deployed`);
+  if (drift.cluster) lines.push(`cluster ${drift.cluster} in the tree, ${deployment.cluster} deployed`);
+  if (drift.namespace) lines.push(`namespace ${drift.namespace} in the tree, ${deployment.namespace} deployed`);
+  if (drift.path) lines.push(`path ${drift.path} in the tree, ${deployment.path} deployed`);
+  if (drift.targetRevision) {
+    lines.push(`tracks ${drift.targetRevision} in the tree, ${deployment.targetRevision} deployed`);
+  }
+  if (drift.images?.length) {
+    lines.push(`pins ${drift.images.join(", ")} in the tree; running ${(deployment.images ?? []).join(", ") || "nothing"}`);
+  }
+  return lines;
+}