@shortlink-org/portolan 0.1.0

package/src/lib/editor-link.ts

@@ -0,0 +1,96 @@
+// A source path, as a link the reader's own editor opens.
+//
+// The forge link answers "show me this file at the built commit". This one
+// answers "let me edit it", which is the question a reader whose own catalog
+// is on screen is actually asking - and going through GitHub to reach a file
+// that is on the disk under the browser is the trip this saves.
+//
+// It needs an absolute path, which only the local server knows: the catalog
+// spells sources relative to the repository, and the browser has no idea
+// where that repository is. So a link exists only in local mode, and the
+// workspace the server reports is joined with the catalog's own path.
+
+import { buildInfo } from "./build-info";
+import type { BuildInfo } from "./build-info";
+import { bare, looksLikePath, splitLine } from "./source-link";
+import type { SourceLocation } from "./source-link";
+
+/** The editors with a URL scheme that opens a file at a line. */
+export const EDITORS = [
+  { id: "vscode", name: "VS Code" },
+  { id: "vscode-insiders", name: "VS Code Insiders" },
+  { id: "cursor", name: "Cursor" },
+  { id: "zed", name: "Zed" },
+  { id: "idea", name: "JetBrains" },
+] as const;
+
+export type EditorId = (typeof EDITORS)[number]["id"];
+
+export const DEFAULT_EDITOR: EditorId = "vscode";
+
+export function isEditorId(value: unknown): value is EditorId {
+  return EDITORS.some((e) => e.id === value);
+}
+
+export function editorName(id: EditorId): string {
+  return EDITORS.find((e) => e.id === id)?.name ?? id;
+}
+
+/**
+ * Join a workspace and a catalog path into one absolute path, or null when
+ * the path is not one the workspace can hold: absolute already, or climbing
+ * out of it. The server refuses those too; refusing here means no dead link.
+ */
+export function absolutePath(workspace: string, path: string): string | null {
+  const root = workspace.replace(/\/+$/, "");
+  if (!root) return null;
+  const clean = path.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!clean || clean.startsWith("/") || clean.split("/").includes("..")) {
+    return null;
+  }
+  return `${root}/${clean}`;
+}
+
+/**
+ * The link that opens `where` - a path, or `path:line` - in `editor`, or null
+ * when there is nothing to open. The path segments are percent-encoded as a
+ * URL's would be, so a space in a directory name survives the scheme.
+ */
+export function editorHref(
+  editor: EditorId,
+  workspace: string,
+  where: string,
+): string | null {
+  const { path, line } = splitLine(where);
+  if (!looksLikePath(path)) return null;
+  const absolute = absolutePath(workspace, path);
+  if (!absolute) return null;
+
+  if (editor === "idea") {
+    const query = new URLSearchParams({ file: absolute });
+    if (line) query.set("line", String(line));
+    return `idea://open?${query.toString()}`;
+  }
+
+  const encoded = absolute.split("/").map(encodeURIComponent).join("/");
+  return `${editor}://file${encoded}${line ? `:${line}` : ""}`;
+}
+
+/**
+ * The catalog path a resolved source can be edited at, or null when the file
+ * is not in this workspace: a service fetched from another repository lives
+ * on the forge, not on the disk under the browser. A path with no forge
+ * behind it is local by definition, and a forge path counts when the forge
+ * is the repository this was built from.
+ */
+export function editorWhere(
+  location: SourceLocation,
+  info: BuildInfo = buildInfo,
+): string | null {
+  if (location.kind === "remote") {
+    if (!info.repoUrl || bare(location.repositoryUrl) !== bare(info.repoUrl)) {
+      return null;
+    }
+  }
+  return location.line ? `${location.path}:${location.line}` : location.path;
+}

package/src/lib/editor-prefs.ts

@@ -0,0 +1,27 @@
+// Which editor the "open in editor" link opens. One key, one value, and the
+// default when nothing is stored or storage is unavailable.
+
+import { DEFAULT_EDITOR, isEditorId } from "./editor-link";
+import type { EditorId } from "./editor-link";
+
+export const EDITOR_KEY = "portolan.editor";
+
+export function parseEditor(raw: string | null | undefined): EditorId {
+  return isEditorId(raw) ? raw : DEFAULT_EDITOR;
+}
+
+export function readEditor(): EditorId {
+  try {
+    return parseEditor(localStorage.getItem(EDITOR_KEY));
+  } catch {
+    return DEFAULT_EDITOR;
+  }
+}
+
+export function writeEditor(editor: EditorId): void {
+  try {
+    localStorage.setItem(EDITOR_KEY, editor);
+  } catch {
+    // A private window keeps the choice for the session in memory only.
+  }
+}

package/src/lib/event-graph.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import { thinCatalog, wideCatalog } from "./scenarios";
+import {
+  bundleById,
+  bundleId,
+  bundles,
+  edgeCount,
+  eventGraph,
+  filterEventGraph,
+  parseBundleId,
+} from "./event-graph";
+
+const sample = eventGraph(catalog);
+
+describe("eventGraph", () => {
+  it("makes a node of every service and every event", () => {
+    expect(sample.services.filter((s) => !s.ghost).map((s) => s.id)).toEqual([
+      "shop.oms",
+      "shop.pricing",
+      // Merge order is source path order, so what the examples publish comes
+      // after the hand-written estate: cart joins shop after its two hand-
+      // written services, and auth's context comes last.
+      "shop.cart",
+      "payments.ledger",
+      "delivery.core",
+      "auth.auth",
+    ]);
+    expect(sample.events.map((e) => e.name)).toContain("PaymentCaptured");
+    // One node per event, whatever the consumer count: PaymentCaptured has two
+    // consumers and is still one pill.
+    const captured = sample.events.filter((e) => e.name === "PaymentCaptured");
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.consumers).toHaveLength(2);
+  });
+
+  it("keeps consumers with no service of their own as ghosts", () => {
+    expect(sample.services.filter((s) => s.ghost).map((s) => s.id)).toEqual([
+      "analytics-sink",
+    ]);
+  });
+
+  it("tints an event by its publisher's context", () => {
+    const captured = sample.events.find((e) => e.name === "PaymentCaptured");
+    expect(captured?.publisher).toBe("payments.ledger");
+    expect(captured?.context).toBe("payments");
+  });
+
+  it("counts what each service publishes and consumes", () => {
+    const ledger = sample.services.find((s) => s.id === "payments.ledger");
+    // PaymentAuthorized, PaymentCaptured, PaymentDeclined, RefundIssued.
+    expect(ledger?.publishes).toBe(4);
+    // OrderPlaced and OrderCancelled.
+    expect(ledger?.consumes).toBe(2);
+  });
+
+  it("carries the consumer the traces showed: auth hears its own PasswordChanged", () => {
+    // The code declares it only by implication - the revoke-sessions flow
+    // opens with the event arriving at auth.auth - and the recording in
+    // examples/auth/telemetry shows it happening, which is what makes the
+    // edge verified rather than derived.
+    const auth = sample.services.find((s) => s.id === "auth.auth");
+    expect(auth?.consumes).toBe(1);
+    const changed = sample.events.find((e) => e.name === "PasswordChanged");
+    expect(changed?.consumers).toMatchObject([
+      { service: "auth.auth", status: "verified", self: true },
+    ]);
+  });
+
+  it("marks self-consumption on the event rather than as an edge", () => {
+    const selfConsumed = eventGraph({
+      ...catalog,
+      contexts: catalog.contexts.map((c) => ({
+        ...c,
+        services: c.services.map((s) => ({
+          ...s,
+          aggregates: s.aggregates.map((a) => ({
+            ...a,
+            events: a.events.map((e) => ({
+              ...e,
+              consumers: [{ service: s.id, status: "verified" as const }],
+            })),
+          })),
+        })),
+      })),
+    });
+    expect(selfConsumed.events.every((e) => e.consumers[0]?.self)).toBe(true);
+    // Never a loop: a self consumption is not a bundle either.
+    expect(bundles(selfConsumed)).toEqual([]);
+  });
+});
+
+describe("filterEventGraph", () => {
+  it("returns the graph untouched when no chip is on", () => {
+    expect(
+      filterEventGraph(sample, { contexts: new Set(), statuses: new Set() }),
+    ).toBe(sample);
+  });
+
+  it("filters services by context and keeps events with one end left", () => {
+    const only = filterEventGraph(sample, {
+      contexts: new Set(["delivery"]),
+      statuses: new Set(),
+    });
+    expect(only.services.map((s) => s.id)).toContain("delivery.core");
+    expect(only.services.map((s) => s.id)).not.toContain("shop.oms");
+    // Everything delivery.core emits survives, and so does everything it is
+    // named as a consumer of - the pills that reach it from outside.
+    const names = only.events.map((e) => e.name);
+    expect(names).toContain("ShipmentDispatched");
+    expect(names).toContain("PaymentCaptured");
+    // But not traffic it has nothing to do with.
+    expect(names).not.toContain("QuoteIssued");
+  });
+
+  it("keeps a ghost alive as long as an event still names it", () => {
+    const only = filterEventGraph(sample, {
+      contexts: new Set(["delivery"]),
+      statuses: new Set(),
+    });
+    expect(only.services.map((s) => s.id)).toContain("analytics-sink");
+  });
+
+  it("hides edges of an unwanted status", () => {
+    const verified = filterEventGraph(sample, {
+      contexts: new Set(),
+      statuses: new Set(["verified"] as const),
+    });
+    const statuses = verified.events.flatMap((e) =>
+      e.consumers.map((c) => c.status),
+    );
+    expect(new Set(statuses)).toEqual(new Set(["verified"]));
+  });
+
+  it("hides an event whose every consumption was filtered out", () => {
+    const verified = filterEventGraph(sample, {
+      contexts: new Set(),
+      statuses: new Set(["verified"] as const),
+    });
+    // QuoteExpired is consumed once, and only as "declared".
+    expect(verified.events.map((e) => e.name)).not.toContain("QuoteExpired");
+  });
+
+  it("keeps an event that never had a consumer to filter", () => {
+    const thin = eventGraph(thinCatalog());
+    const verified = filterEventGraph(thin, {
+      contexts: new Set(),
+      statuses: new Set(["verified"] as const),
+    });
+    expect(verified.events).toHaveLength(3);
+  });
+
+  it("reports how many edges a filter is hiding", () => {
+    const before = edgeCount(sample);
+    const after = edgeCount(
+      filterEventGraph(sample, {
+        contexts: new Set(["delivery"]),
+        statuses: new Set(),
+      }),
+    );
+    expect(after).toBeLessThan(before);
+    expect(before - after).toBeGreaterThan(0);
+  });
+});
+
+describe("bundles", () => {
+  it("collapses every event of a pair into one edge with a count", () => {
+    const pair = bundles(sample).find(
+      (b) => b.from === "payments.ledger" && b.to === "delivery.core",
+    );
+    expect(pair?.events.map((e) => e.name).sort()).toEqual([
+      "PaymentAuthorized",
+      "PaymentCaptured",
+      "RefundIssued",
+    ]);
+    // Worst wins: two of the three are only declared.
+    expect(pair?.status).toBe("declared");
+  });
+
+  it("draws one edge per ordered pair, never one per event", () => {
+    const all = bundles(sample);
+    const pairs = new Set(all.map((b) => `${b.from}->${b.to}`));
+    expect(pairs.size).toBe(all.length);
+  });
+
+  it("flags a pair that publishes both ways so the canvas can offset it", () => {
+    const there = bundles(sample).find(
+      (b) => b.from === "shop.oms" && b.to === "payments.ledger",
+    );
+    const back = bundles(sample).find(
+      (b) => b.from === "payments.ledger" && b.to === "shop.oms",
+    );
+    expect(there?.back).toBe(true);
+    expect(back?.back).toBe(true);
+  });
+
+  it("round-trips its id", () => {
+    const id = bundleId("a.b", "c.d");
+    expect(parseBundleId(id)).toEqual({ from: "a.b", to: "c.d" });
+    expect(parseBundleId("shop.oms")).toBeNull();
+    expect(bundleById(sample, id)).toBeNull();
+    expect(
+      bundleById(sample, bundleId("payments.ledger", "delivery.core"))?.events,
+    ).toHaveLength(3);
+  });
+});
+
+describe("the thin estate", () => {
+  const thin = eventGraph(thinCatalog());
+
+  it("is one service and three events with nothing listening", () => {
+    expect(thin.services).toHaveLength(1);
+    expect(thin.events).toHaveLength(3);
+    expect(thin.events.every((e) => e.consumers.length === 0)).toBe(true);
+  });
+
+  it("still draws a line from the service to each of its events", () => {
+    expect(edgeCount(thin)).toBe(3);
+  });
+
+  it("has no bundle at all, because nothing reaches anything", () => {
+    expect(bundles(thin)).toEqual([]);
+  });
+});
+
+describe("the wide estate", () => {
+  const wide = eventGraph(wideCatalog());
+
+  it("is forty services and eighty events", () => {
+    expect(wide.services.filter((s) => !s.ghost)).toHaveLength(40);
+    expect(wide.events).toHaveLength(80);
+  });
+
+  it("still has ghosts in it", () => {
+    expect(wide.services.filter((s) => s.ghost).length).toBeGreaterThan(0);
+  });
+});

package/src/lib/event-graph.ts

@@ -0,0 +1,327 @@
+// The dependency graph's model: services AND events are nodes.
+//
+// The old shape drew one labelled arrow per (event, consumer) pair, so an
+// event with four consumers was four lines carrying the same word four times.
+// The word was the densest thing on the canvas and it was also the most
+// duplicated. Promoting the event to a node fixes both at once: it is written
+// once, it is a thing a reader can click, and every line around it can then be
+// bare - the node IS the label.
+//
+// Two derivations live here. `eventGraph` is the bipartite one; `bundles`
+// collapses it back to services only, one edge per ordered pair with a count.
+// Both are pure, so the acceptance criteria are assertions rather than
+// eyeballing.
+
+import type { Catalog, Status } from "../catalog";
+
+/** Worst wins: a bundle is known no better than its least-known event. */
+export function worstStatus(statuses: readonly Status[]): Status {
+  if (statuses.includes("unresolved")) return "unresolved";
+  if (statuses.includes("declared")) return "declared";
+  return "verified";
+}
+
+export interface GraphService {
+  id: string;
+  label: string;
+  context: string | null;
+  /** named as a consumer but absent from the catalog */
+  ghost: boolean;
+  /** events it publishes */
+  publishes: number;
+  /** distinct events it consumes, its own included */
+  consumes: number;
+}
+
+export interface EventConsumer {
+  service: string;
+  status: Status;
+  /**
+   * The consumer is the publisher. It is held here rather than dropped so the
+   * status filter treats it like any other consumption; the canvas renders it
+   * as a chip on the pill, never as a loop edge.
+   */
+  self: boolean;
+}
+
+export interface GraphEvent {
+  id: string;
+  name: string;
+  /** service id; the pill is tinted by this service's context */
+  publisher: string;
+  context: string | null;
+  consumers: EventConsumer[];
+}
+
+export interface EventGraph {
+  services: GraphService[];
+  events: GraphEvent[];
+}
+
+/** Services in catalog order, events grouped by publisher in the same order. */
+export function eventGraph(catalog: Catalog): EventGraph {
+  const services = new Map<string, GraphService>();
+  const events: GraphEvent[] = [];
+
+  const blank = (id: string, context: string | null, ghost: boolean) => ({
+    id,
+    label: id,
+    context,
+    ghost,
+    publishes: 0,
+    consumes: 0,
+  });
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      services.set(service.id, blank(service.id, context.id, false));
+    }
+  }
+
+  for (const context of catalog.contexts) {
+    for (const service of context.services) {
+      for (const aggregate of service.aggregates) {
+        for (const event of aggregate.events) {
+          const consumers: EventConsumer[] = event.consumers.map((c) => ({
+            service: c.service,
+            status: c.status,
+            self: c.service === service.id,
+          }));
+          for (const consumer of consumers) {
+            // A consumer with no service of its own is still a real
+            // dependency. Drawing it as a ghost keeps the gap visible instead
+            // of hiding it.
+            if (!services.has(consumer.service)) {
+              services.set(consumer.service, blank(consumer.service, null, true));
+            }
+          }
+          events.push({
+            id: event.id,
+            name: event.name,
+            publisher: service.id,
+            context: context.id,
+            consumers,
+          });
+        }
+      }
+    }
+  }
+
+  return { services: [...services.values()], events: counted(events, services) };
+}
+
+/** Fills in each service's two footer numbers from the events around it. */
+function counted(
+  events: GraphEvent[],
+  services: Map<string, GraphService>,
+): GraphEvent[] {
+  for (const event of events) {
+    const publisher = services.get(event.publisher);
+    if (publisher) publisher.publishes += 1;
+    // Distinct, because one event consumed twice by the same service is still
+    // one thing that service listens to.
+    const seen = new Set<string>();
+    for (const consumer of event.consumers) {
+      if (seen.has(consumer.service)) continue;
+      seen.add(consumer.service);
+      const service = services.get(consumer.service);
+      if (service) service.consumes += 1;
+    }
+  }
+  return events;
+}
+
+// ---------------------------------------------------------------------------
+// Filters
+// ---------------------------------------------------------------------------
+
+export interface GraphFilter {
+  /** Active context chips. Empty means every context. */
+  contexts: ReadonlySet<string>;
+  /** Active status chips. Empty means every status. */
+  statuses: ReadonlySet<Status>;
+}
+
+export const NO_FILTER: GraphFilter = {
+  contexts: new Set(),
+  statuses: new Set(),
+};
+
+/**
+ * How many lines the canvas would draw for a graph: one per event that has a
+ * publisher to hang off, plus one per consumption that is not the publisher
+ * listening to itself.
+ *
+ * The header subtracts a filtered count from an unfiltered one to say how many
+ * edges a chip is hiding, so "edge" has to mean exactly one drawn line.
+ */
+export function edgeCount(graph: EventGraph): number {
+  const present = new Set(graph.services.map((s) => s.id));
+  let n = 0;
+  for (const event of graph.events) {
+    if (present.has(event.publisher)) n += 1;
+    for (const consumer of event.consumers) {
+      if (!consumer.self && present.has(consumer.service)) n += 1;
+    }
+  }
+  return n;
+}
+
+/**
+ * The graph a set of chips leaves standing.
+ *
+ * Contexts filter SERVICES, and only services. An event survives if either end
+ * of it does, so filtering to one context still shows what that context emits
+ * into the dark and what reaches it from outside - the pill keeps its
+ * publisher's colour, which is what says the traffic comes from somewhere no
+ * longer on screen.
+ *
+ * Statuses filter CONSUMPTIONS, and only consumptions. An event that had
+ * consumers and has none left is hidden: an empty pill under a "verified only"
+ * filter would read as an event nobody consumes, which is a different fact and
+ * a false one. An event that never had consumers is not hidden by a status
+ * filter, because it never held a status to disagree with.
+ *
+ * A ghost is neither: it has no context to be filtered by and exists only
+ * because an event named it, so it lives and dies with the events that do.
+ */
+export function filterEventGraph(
+  graph: EventGraph,
+  filter: GraphFilter,
+): EventGraph {
+  const byContext = filter.contexts.size > 0;
+  const byStatus = filter.statuses.size > 0;
+  if (!byContext && !byStatus) return graph;
+
+  const ghosts = new Set(
+    graph.services.filter((s) => s.ghost).map((s) => s.id),
+  );
+  const kept = new Set(
+    graph.services
+      .filter(
+        (s) =>
+          !s.ghost &&
+          (!byContext ||
+            (s.context !== null && filter.contexts.has(s.context))),
+      )
+      .map((s) => s.id),
+  );
+
+  const passes = (c: EventConsumer): boolean =>
+    !byStatus || filter.statuses.has(c.status);
+
+  const events: GraphEvent[] = [];
+  const liveGhosts = new Set<string>();
+  for (const event of graph.events) {
+    const consumers = event.consumers.filter(passes);
+    if (byStatus && event.consumers.length > 0 && consumers.length === 0) {
+      continue;
+    }
+    // Only a real service can justify an event: a ghost is the far end of a
+    // dependency, never a reason to draw one.
+    const anchored =
+      kept.has(event.publisher) ||
+      consumers.some((c) => kept.has(c.service));
+    if (!anchored) continue;
+
+    const surviving = consumers.filter(
+      (c) => kept.has(c.service) || ghosts.has(c.service),
+    );
+    for (const consumer of surviving) {
+      if (ghosts.has(consumer.service)) liveGhosts.add(consumer.service);
+    }
+    events.push({ ...event, consumers: surviving });
+  }
+
+  return {
+    services: graph.services.filter(
+      (s) => kept.has(s.id) || liveGhosts.has(s.id),
+    ),
+    events,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Compact mode: services only, one bundled edge per ordered pair.
+// ---------------------------------------------------------------------------
+
+export interface BundleEvent {
+  id: string;
+  name: string;
+  status: Status;
+}
+
+export interface Bundle {
+  /** "bundle:<from>><to>" - a selection id, so the rail can resolve it */
+  id: string;
+  from: string;
+  to: string;
+  events: BundleEvent[];
+  /** worst status among the events it carries */
+  status: Status;
+  /** the reverse pair also exists, so the canvas has to offset both */
+  back: boolean;
+}
+
+export function bundleId(from: string, to: string): string {
+  return `bundle:${from}>${to}`;
+}
+
+export function parseBundleId(id: string): { from: string; to: string } | null {
+  if (!id.startsWith("bundle:")) return null;
+  const body = id.slice(7);
+  const at = body.indexOf(">");
+  if (at <= 0 || at === body.length - 1) return null;
+  return { from: body.slice(0, at), to: body.slice(at + 1) };
+}
+
+/**
+ * One entry per ordered pair, in the order the pairs first appear.
+ *
+ * Self-consumption never becomes a bundle: an arrow from a box back to itself
+ * is a loop, and a loop is the one shape a layered router cannot place without
+ * drawing a circle around the node it belongs to.
+ */
+export function bundles(graph: EventGraph): Bundle[] {
+  const byPair = new Map<string, Bundle>();
+  const present = new Set(graph.services.map((s) => s.id));
+
+  for (const event of graph.events) {
+    if (!present.has(event.publisher)) continue;
+    for (const consumer of event.consumers) {
+      if (consumer.self || !present.has(consumer.service)) continue;
+      const id = bundleId(event.publisher, consumer.service);
+      const found = byPair.get(id);
+      const carried: BundleEvent = {
+        id: event.id,
+        name: event.name,
+        status: consumer.status,
+      };
+      if (found) {
+        found.events.push(carried);
+        found.status = worstStatus(found.events.map((e) => e.status));
+      } else {
+        byPair.set(id, {
+          id,
+          from: event.publisher,
+          to: consumer.service,
+          events: [carried],
+          status: consumer.status,
+          back: false,
+        });
+      }
+    }
+  }
+
+  for (const bundle of byPair.values()) {
+    bundle.back = byPair.has(bundleId(bundle.to, bundle.from));
+  }
+  return [...byPair.values()];
+}
+
+/** The bundle a selection id names, or null. Used by the detail rail. */
+export function bundleById(graph: EventGraph, id: string): Bundle | null {
+  const parsed = parseBundleId(id);
+  if (!parsed) return null;
+  return bundles(graph).find((b) => b.id === id) ?? null;
+}