@shortlink-org/portolan 0.3.0 → 0.4.0

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;
+}

package/src/lib/derive.ts

@@ -2,12 +2,14 @@
 // so every number a Phase 2 page shows can be asserted in a test.
 
 import type {
+  Aggregate,
   Block,
   BoundedContext,
   Catalog,
   Event,
   Field,
   Flow,
+  Operation,
   Service,
   Step,
 } from "../catalog";
@@ -185,6 +187,38 @@ export interface StepRef {
   number: number;
 }
 
+/**
+ * The flows in which an operation runs: one whose step carries the
+ * operation's own ref, `<aggregate id>/<operation id>` - a call across a
+ * boundary - or whose incoming rpc step is a method the operation says
+ * exposes it. Each flow once, at its first such step.
+ */
+export function flowsRunning(
+  catalog: Catalog,
+  service: Service,
+  aggregate: Aggregate,
+  operation: Operation,
+): StepRef[] {
+  const own = `${aggregate.id}/${operation.id}`;
+  const methods = new Set(
+    (operation.exposedBy ?? []).flatMap((method) =>
+      service.provides.map((provided) => `${provided.id}/${method}`),
+    ),
+  );
+  const out: StepRef[] = [];
+  for (const flow of catalog.flows) {
+    const steps = walkSteps(flow.steps);
+    const i = steps.findIndex(
+      (step) =>
+        step.ref !== undefined &&
+        (step.ref === own || (step.kind === "rpc" && methods.has(step.ref))),
+    );
+    const hit = steps[i];
+    if (hit) out.push({ flow, stepId: hit.id, number: i + 1 });
+  }
+  return out;
+}
+
 /** Every step across every flow that references an event, with its 1-based number. */
 export function stepsReferencing(catalog: Catalog, eventId: string): StepRef[] {
   const out: StepRef[] = [];
@@ -404,29 +438,6 @@ export function usesOfDef(catalog: Catalog, defId: string): DefUse {
 // Problems
 // ---------------------------------------------------------------------------
 
-/**
- * One edge in the estate that does not land. Two things can be wrong, and they
- * are wrong in the same way: a service calls an rpc whose provider is not in
- * the catalog, or an event names a consumer that is not either. Both mean the
- * chart draws an arrow into open water.
- */
-export type ProblemKind =
-  | "rpc"
-  | "consumer"
-  | "cross-service-fk"
-  | "cross-service-lineage"
-  | "shared-store"
-  | "persistence-drift"
-  | "column-type"
-  | "outbox-payload"
-  | "proto-missing"
-  | "proto-drift"
-  | "shared-channel"
-  | "channel-undeclared"
-  | "channel-unpublished"
-  | "message-encoding"
-  | "subscription-unresolved";
-
 /**
  * How wrong a problem is. Two values, not five: an edge either lands somewhere
  * the catalog knows about or it does not (an error), or the catalog holds two
@@ -435,26 +446,27 @@ export type ProblemKind =
  */
 export type Severity = "error" | "warning";
 
+/**
+ * One row of the Problems page: what a rule found, from the near end the
+ * reader can see. Every rule is CEL over one subject (rules/builtin.json for
+ * the ones the package ships, `problemRules` in the manifest for the estate's
+ * own), and `rule` says which; the subject says where `id` leads.
+ */
 export interface Problem {
-  kind: ProblemKind;
+  rule: string;
   severity: Severity;
   /** The context that owns the end we can see. */
   context: string;
   /** The service that owns the end we can see. */
   service: string;
-  /** The call id or the event id - what is on the near end of the edge. */
+  /** What is on the near end of the edge: the subject's id. */
   id: string;
-  /** The name that resolves to nothing. */
+  /** The far end, when the rule names one. */
   peer: string;
   note: string | undefined;
   source: string | undefined;
 }
 
-/**
- * Every unresolved edge, contexts in catalog order. Nothing is scored and
- * nothing is ranked: an unresolved consumer is exactly as broken as an
- * unresolved call, and sorting them by badness would invent a fact.
- */
 /**
  * How many edges there were to resolve at all - every rpc call a service makes
  * and every consumer an event names, whatever their status.
@@ -477,41 +489,3 @@ export function edgeCount(catalog: Catalog): number {
   return n;
 }
 
-export function problems(catalog: Catalog): Problem[] {
-  const out: Problem[] = [];
-  for (const context of catalog.contexts) {
-    for (const service of context.services) {
-      for (const call of service.consumes) {
-        if (call.status !== "unresolved") continue;
-        out.push({
-          kind: "rpc",
-          severity: "error",
-          context: context.id,
-          service: service.id,
-          id: call.id,
-          peer: call.peer,
-          note: call.note,
-          source: call.source,
-        });
-      }
-      for (const aggregate of service.aggregates) {
-        for (const event of aggregate.events) {
-          for (const consumer of event.consumers) {
-            if (consumer.status !== "unresolved") continue;
-            out.push({
-              kind: "consumer",
-              severity: "error",
-              context: context.id,
-              service: service.id,
-              id: event.id,
-              peer: consumer.service,
-              note: consumer.note,
-              source: undefined,
-            });
-          }
-        }
-      }
-    }
-  }
-  return out;
-}

package/src/lib/environments.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import type { Catalog, Deployment } from "../catalog";
+import { narrowToEnvironments, servicesDeployedIn } from "./environments";
+
+const service = (id: string, path: string) => ({
+  id,
+  slug: id.split(".")[1] ?? id,
+  name: id,
+  repo: "github.com/acme/shop",
+  path,
+  readme: "",
+  provides: [],
+  consumes: [],
+  aggregates: [],
+});
+
+const placed = (name: string, environment: string, path: string, extra: Partial<Deployment> = {}): Deployment => ({
+  id: `argocd/${name}`,
+  name,
+  project: "shop",
+  environment,
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo: "github.com/acme/shop",
+  path,
+  targetRevision: "main",
+  revision: "a".repeat(40),
+  tool: "kustomize",
+  url: `https://argocd.example.com/applications/argocd/${name}`,
+  ...extra,
+});
+
+const catalog: Catalog = {
+  generatedAt: "",
+  commit: "",
+  contexts: [
+    {
+      id: "shop",
+      slug: "shop",
+      name: "Shop",
+      summary: "",
+      services: [service("shop.cart", "services/cart"), service("shop.oms", "services/oms")],
+    },
+    {
+      id: "payments",
+      slug: "payments",
+      name: "Payments",
+      summary: "",
+      services: [service("payments.ledger", "services/ledger")],
+    },
+  ],
+  defs: {},
+  flows: [],
+  adrs: [],
+  deployments: [
+    placed("cart", "prod", "services/cart/deploy"),
+    placed("cart-staging", "staging", "services/cart/deploy"),
+    placed("oms", "prod", "services/oms/deploy"),
+    // No environment label and no cluster name: placed by the one word left.
+    placed("ledger", "", "services/ledger/deploy", { cluster: "" }),
+  ],
+};
+
+describe("the estate narrowed to an environment", () => {
+  it("names the services the snapshot places in the environments asked for", () => {
+    expect([...servicesDeployedIn(catalog, new Set(["prod"]))]).toEqual(["shop.cart", "shop.oms"]);
+    expect([...servicesDeployedIn(catalog, new Set(["staging"]))]).toEqual(["shop.cart"]);
+    expect([...servicesDeployedIn(catalog, new Set(["prod", "staging"]))]).toEqual(["shop.cart", "shop.oms"]);
+    expect([...servicesDeployedIn(catalog, new Set(["unplaced"]))]).toEqual(["payments.ledger"]);
+    expect(servicesDeployedIn(catalog, new Set(["nowhere"])).size).toBe(0);
+  });
+
+  it("keeps only the deployed services, drops a context left empty, and leaves the rest of the catalog alone", () => {
+    const staging = narrowToEnvironments(catalog, new Set(["staging"]));
+    expect(staging.contexts.map((c) => [c.id, c.services.map((s) => s.id)])).toEqual([["shop", ["shop.cart"]]]);
+    expect(staging.deployments).toBe(catalog.deployments);
+    expect(staging.flows).toBe(catalog.flows);
+  });
+
+  it("is the whole estate when no environment is chosen", () => {
+    expect(narrowToEnvironments(catalog, new Set())).toBe(catalog);
+  });
+});

package/src/lib/environments.ts

@@ -0,0 +1,57 @@
+// The estate narrowed to what runs somewhere.
+//
+// A map answers "who leans on whom"; with an environment chosen it answers
+// "who leans on whom IN STAGING" - and the honest way to answer that is to
+// take the services the snapshot does not place there out of the catalog
+// and let the same graph, map and counts run over what is left. A call to
+// a service that is not deployed there is then an edge that leaves the
+// chart, which is what it is. Nothing here is a second graph; it is the
+// first graph over a smaller estate.
+
+import type { Catalog } from "../catalog";
+import { allDeployments, deploys, environmentOf } from "../catalog";
+
+/** The ids of the services the snapshot places in any of the environments named. */
+export function servicesDeployedIn(
+  catalog: Catalog,
+  environments: ReadonlySet<string>,
+): Set<string> {
+  const placed = allDeployments(catalog).filter((deployment) =>
+    environments.has(environmentOf(deployment)),
+  );
+  const out = new Set<string>();
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      if (placed.some((deployment) => deploys(deployment, service))) {
+        out.add(service.id);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * The catalog with only the services deployed in the environments named,
+ * and only the contexts that still hold one. No environment named is the
+ * whole estate: an empty filter is no filter, as everywhere else in the app.
+ *
+ * Flows, ADRs, stores and terms are left as they are: a flow through a
+ * service that is not in staging is still the flow, and the reader asked
+ * about the map, not the archive.
+ */
+export function narrowToEnvironments(
+  catalog: Catalog,
+  environments: ReadonlySet<string>,
+): Catalog {
+  if (environments.size === 0) return catalog;
+  const kept = servicesDeployedIn(catalog, environments);
+  return {
+    ...catalog,
+    contexts: catalog.contexts
+      .map((context) => ({
+        ...context,
+        services: context.services.filter((service) => kept.has(service.id)),
+      }))
+      .filter((context) => context.services.length > 0),
+  };
+}

package/src/lib/integration-url.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { createIntegrationStore, normalizeIntegrationUrl } from "./integration-url";
+
+describe("integration URLs", () => {
+  it("accepts web URLs and rejects values that cannot be opened safely", () => {
+    expect(normalizeIntegrationUrl(" https://docs.example/ ")).toBe(
+      "https://docs.example",
+    );
+    expect(normalizeIntegrationUrl("https://docs.example/wiki#top")).toBe(
+      "https://docs.example/wiki",
+    );
+    expect(normalizeIntegrationUrl("javascript:alert(1)")).toBeNull();
+    expect(normalizeIntegrationUrl("not a URL")).toBeNull();
+    expect(normalizeIntegrationUrl("  ")).toBe("");
+  });
+
+  it("keeps a normalized value and ignores one that cannot be opened", () => {
+    // vitest runs under node, so the store keeps the value for this session
+    // only; what is asserted is the behaviour the page sees either way.
+    const store = createIntegrationStore("portolan.integrations.test");
+    store.getState().setUrl("https://docs.example/");
+    expect(store.getState().url).toBe("https://docs.example");
+
+    store.getState().setUrl("javascript:alert(1)");
+    expect(store.getState().url).toBe("https://docs.example");
+
+    store.getState().setUrl("");
+    expect(store.getState().url).toBe("");
+  });
+});