@shortlink-org/portolan 0.1.0

package/src/selection/model.ts

@@ -0,0 +1,473 @@
+// What "selected" means. One value, one shape, no per-panel variants.
+//
+// A selection is a kind and an id. The id is always a catalog id, spelled the
+// way the catalog spells it — never a slug, never a LikeC4 identifier. The kind
+// is derived from the id rather than supplied by the caller, so a click in the
+// sidebar and a click on a diagram node cannot disagree about what was clicked.
+
+import type {
+  Aggregate,
+  BoundedContext,
+  Column,
+  Event,
+  Flow,
+  ProtoModule,
+  Service,
+  Step,
+  Store,
+  Table,
+  TypeDef,
+  View,
+} from "../catalog";
+import { walkSteps } from "../catalog";
+import { catalog, index } from "../data";
+import { bundleById, eventGraph, parseBundleId } from "../lib/event-graph";
+import type { Bundle } from "../lib/event-graph";
+
+export type SelectionKind =
+  | "context"
+  | "service"
+  | "aggregate"
+  | "store"
+  | "table"
+  | "view"
+  | "column"
+  | "event"
+  | "value-object"
+  | "flow-step"
+  | "bundle"
+  | "module"
+  | "unknown";
+
+export interface Selection {
+  kind: SelectionKind;
+  id: string;
+}
+
+/** Where a selection came from. Subscribers use it to avoid echoing themselves. */
+export type SelectionSource =
+  | "sidebar"
+  | "breadcrumb"
+  | "diagram"
+  | "palette"
+  | "panel"
+  | "page"
+  | "rail"
+  | "url";
+
+// ---------------------------------------------------------------------------
+// Flow steps. A step id is only unique inside its flow, so the selection id
+// carries the flow with it. The flow slug never contains a slash, so one split
+// is enough to take it apart again.
+// ---------------------------------------------------------------------------
+
+export function flowStepId(flowSlug: string, stepId: string): string {
+  return `${flowSlug}/${stepId}`;
+}
+
+export function parseFlowStepId(
+  id: string,
+): { flowSlug: string; stepId: string } | null {
+  const at = id.indexOf("/");
+  if (at <= 0 || at === id.length - 1) return null;
+  return { flowSlug: id.slice(0, at), stepId: id.slice(at + 1) };
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+export interface ResolvedContext {
+  kind: "context";
+  id: string;
+  context: BoundedContext;
+}
+export interface ResolvedService {
+  kind: "service";
+  id: string;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedAggregate {
+  kind: "aggregate";
+  id: string;
+  aggregate: Aggregate;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedEvent {
+  kind: "event";
+  id: string;
+  event: Event;
+  aggregate: Aggregate;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedStore {
+  kind: "store";
+  id: string;
+  store: Store;
+  /** The service that OWNS it. A reader of the store resolves to the owner too. */
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedModule {
+  kind: "module";
+  id: string;
+  module: ProtoModule;
+}
+export interface ResolvedTable {
+  kind: "table";
+  id: string;
+  table: Table;
+  store: Store;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedView {
+  kind: "view";
+  id: string;
+  view: View;
+  store: Store;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedColumn {
+  kind: "column";
+  id: string;
+  column: Column;
+  /** The table holding it, or null when the column belongs to a view. */
+  table: Table | null;
+  /** The view declaring it, or null when the column belongs to a table. */
+  view: View | null;
+  store: Store;
+  service: Service;
+  context: BoundedContext;
+}
+export interface ResolvedValueObject {
+  kind: "value-object";
+  id: string;
+  def: TypeDef;
+}
+/**
+ * Every event one service publishes to another, as one thing.
+ *
+ * Compact mode draws that as a single line with a count on it, and a line
+ * standing for three events has to be selectable or the count is a number the
+ * reader cannot open. Like a flow step, it has no entity of its own in the
+ * catalog: its id is synthetic and it is resolved by re-deriving the graph.
+ */
+export interface ResolvedBundle {
+  kind: "bundle";
+  id: string;
+  bundle: Bundle;
+  /** null when the far end is a consumer the catalog has never heard of */
+  from: Service | null;
+  to: Service | null;
+}
+export interface ResolvedFlowStep {
+  kind: "flow-step";
+  id: string;
+  flow: Flow;
+  step: Step;
+  /** 1-based position in the flow's step order, the number the rail shows. */
+  number: number;
+}
+
+export type Resolved =
+  | ResolvedContext
+  | ResolvedService
+  | ResolvedAggregate
+  | ResolvedStore
+  | ResolvedTable
+  | ResolvedView
+  | ResolvedColumn
+  | ResolvedEvent
+  | ResolvedValueObject
+  | ResolvedFlowStep
+  | ResolvedBundle
+  | ResolvedModule;
+
+/**
+ * The whole mapping layer: a catalog id in, a catalog entity out. Anything the
+ * catalog does not know about resolves to null, and the caller is expected to
+ * carry on with a selection of kind "unknown" rather than to drop the click.
+ */
+export function resolveSelection(id: string): Resolved | null {
+  // First, because it is the only id with a literal prefix: nothing in the
+  // catalog is spelled "bundle:...", so there is nothing for it to shadow.
+  if (parseBundleId(id)) {
+    const bundle = bundleById(eventGraph(catalog), id);
+    if (!bundle) return null;
+    return {
+      kind: "bundle",
+      id,
+      bundle,
+      from: index.serviceById.get(bundle.from) ?? null,
+      to: index.serviceById.get(bundle.to) ?? null,
+    };
+  }
+
+  const event = index.eventById.get(id);
+  if (event) {
+    const owner = index.eventOwner.get(id);
+    const context = owner ? index.serviceContext.get(owner.service.id) : null;
+    if (owner && context) {
+      return {
+        kind: "event",
+        id,
+        event,
+        aggregate: owner.aggregate,
+        service: owner.service,
+        context,
+      };
+    }
+  }
+
+  const aggregate = index.aggregateById.get(id);
+  if (aggregate) {
+    const service = index.aggregateOwner.get(id);
+    const context = service ? index.serviceContext.get(service.id) : null;
+    if (service && context) {
+      return { kind: "aggregate", id, aggregate, service, context };
+    }
+  }
+
+  const service = index.serviceById.get(id);
+  if (service) {
+    const context = index.serviceContext.get(id);
+    if (context) return { kind: "service", id, service, context };
+  }
+
+  // Column before table before store: the three ids are nested prefixes of one
+  // another, and the longest one is the thing that was actually clicked. A
+  // view column is looked up in the same breath as a table column — a reader
+  // clicking a row does not know or care which of the two they are on.
+  const column = index.columnById.get(id);
+  if (column) {
+    const owner = ownerOfStore(column.store);
+    if (owner) {
+      return {
+        kind: "column",
+        id,
+        column: column.column,
+        table: column.table,
+        view: null,
+        store: column.store,
+        ...owner,
+      };
+    }
+  }
+
+  const viewColumn = index.viewColumnById.get(id);
+  if (viewColumn) {
+    const owner = ownerOfStore(viewColumn.store);
+    if (owner) {
+      return {
+        kind: "column",
+        id,
+        column: viewColumn.column,
+        table: null,
+        view: viewColumn.view,
+        store: viewColumn.store,
+        ...owner,
+      };
+    }
+  }
+
+  const table = index.tableById.get(id);
+  if (table) {
+    const owner = ownerOfStore(table.store);
+    if (owner) {
+      return {
+        kind: "table",
+        id,
+        table: table.table,
+        store: table.store,
+        ...owner,
+      };
+    }
+  }
+
+  const view = index.viewById.get(id);
+  if (view) {
+    const owner = ownerOfStore(view.store);
+    if (owner) {
+      return {
+        kind: "view",
+        id,
+        view: view.view,
+        store: view.store,
+        ...owner,
+      };
+    }
+  }
+
+  const store = index.storeById.get(id);
+  if (store) {
+    const owner = ownerOfStore(store);
+    if (owner) return { kind: "store", id, store, ...owner };
+  }
+
+  // A module id carries a slash - `buf.build/acme/shop` - so it can shadow
+  // nothing above it, but it is looked up late all the same: the domain tree is
+  // what a reader is usually pointing at.
+  const module = index.moduleById.get(id);
+  if (module) return { kind: "module", id, module };
+
+  const context = catalog.contexts.find((c) => c.id === id);
+  if (context) return { kind: "context", id, context };
+
+  const def = catalog.defs[id];
+  if (def) return { kind: "value-object", id, def };
+
+  const parsed = parseFlowStepId(id);
+  if (parsed) {
+    const flow = index.flowBySlug.get(parsed.flowSlug);
+    if (flow) {
+      const steps = walkSteps(flow.steps);
+      const at = steps.findIndex((s) => s.id === parsed.stepId);
+      const step = at < 0 ? undefined : steps[at];
+      if (step) return { kind: "flow-step", id, flow, step, number: at + 1 };
+    }
+  }
+
+  return null;
+}
+
+/** The service that owns a store, and the context that owns the service. */
+function ownerOfStore(
+  store: Store,
+): { service: Service; context: BoundedContext } | null {
+  const service = index.serviceById.get(store.owner);
+  const context = index.serviceContext.get(store.owner);
+  return service && context ? { service, context } : null;
+}
+
+/** The kind an id resolves to, or "unknown" when nothing in the catalog owns it. */
+export function classify(id: string): SelectionKind {
+  return resolveSelection(id)?.kind ?? "unknown";
+}
+
+/**
+ * A selection for any id at all. An id with no catalog counterpart still
+ * selects — as "unknown" — because a diagram node the catalog has never heard
+ * of is a fact worth showing, not a click to swallow.
+ */
+export function selectionFor(id: string): Selection {
+  return { kind: classify(id), id };
+}
+
+export function sameSelection(
+  a: Selection | null,
+  b: Selection | null,
+): boolean {
+  if (a === null || b === null) return a === b;
+  return a.kind === b.kind && a.id === b.id;
+}
+
+/** Ancestors first, then the entity itself: the trail a breadcrumb walks. */
+export function selectionTrail(selection: Selection): Selection[] {
+  const resolved = resolveSelection(selection.id);
+  if (!resolved) return [selection];
+  switch (resolved.kind) {
+    case "context":
+      return [{ kind: "context", id: resolved.context.id }];
+    case "service":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+      ];
+    case "aggregate":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "aggregate", id: resolved.aggregate.id },
+      ];
+    case "event":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "aggregate", id: resolved.aggregate.id },
+        { kind: "event", id: resolved.event.id },
+      ];
+    case "store":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "store", id: resolved.store.id },
+      ];
+    case "table":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "store", id: resolved.store.id },
+        { kind: "table", id: resolved.table.id },
+      ];
+    case "view":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "store", id: resolved.store.id },
+        { kind: "view", id: resolved.view.id },
+      ];
+    // The relation the column belongs to sits in the trail whichever kind it
+    // is; a column of a view has a view where a table would be, and nothing
+    // else about the walk changes.
+    case "column":
+      return [
+        { kind: "context", id: resolved.context.id },
+        { kind: "service", id: resolved.service.id },
+        { kind: "store", id: resolved.store.id },
+        ...(resolved.view
+          ? [{ kind: "view" as const, id: resolved.view.id }]
+          : resolved.table
+            ? [{ kind: "table" as const, id: resolved.table.id }]
+            : []),
+        { kind: "column", id: resolved.id },
+      ];
+    case "flow-step":
+    case "value-object":
+    case "bundle":
+    // A module has no ancestor in the catalog. That is the point of it sitting
+    // at the estate level: it is published by one service and read by four, so
+    // there is no single parent a breadcrumb could honestly walk back through.
+    case "module":
+      return [selection];
+  }
+}
+
+/** Short label for a selection, for chips and breadcrumbs. */
+export function selectionLabel(selection: Selection): string {
+  const resolved = resolveSelection(selection.id);
+  if (!resolved) return selection.id;
+  switch (resolved.kind) {
+    case "context":
+      return resolved.context.id;
+    case "service":
+      return resolved.service.slug;
+    case "aggregate":
+      return resolved.aggregate.slug;
+    case "event":
+      return resolved.event.name;
+    case "store":
+      return resolved.store.slug;
+    case "table":
+      return resolved.table.name;
+    case "view":
+      return resolved.view.name;
+    case "column":
+      return `${resolved.view?.name ?? resolved.table?.name ?? resolved.store.slug}.${resolved.column.name}`;
+    case "value-object":
+      return resolved.id;
+    case "flow-step":
+      return `${resolved.flow.slug} · step ${resolved.number}`;
+    case "bundle":
+      return `${resolved.bundle.from} → ${resolved.bundle.to}`;
+    // `acme/shop` rather than `buf.build/acme/shop`: the registry host is the
+    // same for every module in almost every estate, and repeating it in a chip
+    // spends the width on the half that says nothing.
+    case "module":
+      return resolved.module.name;
+  }
+}

package/src/selection/pages.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { pageContains, selectionPath } from "./pages";
+import { selectionFor } from "./model";
+
+const dispatched = selectionFor("delivery.core.shipment.ShipmentDispatched");
+const shipment = selectionFor("delivery.core.shipment");
+const money = selectionFor("Money");
+
+describe("pageContains", () => {
+  it("holds an aggregate's events on the aggregate page", () => {
+    expect(pageContains("/c/delivery/core/shipment", dispatched)).toBe(true);
+    expect(pageContains("/c/delivery/core/shipment", shipment)).toBe(true);
+  });
+
+  // The literal segment is not an event slug. Without this a block page claims
+  // to hold every event of its aggregate, and the palette refuses to navigate.
+  it("holds nothing on a value object or entity page", () => {
+    expect(
+      pageContains("/c/delivery/core/shipment/entity/parcel", dispatched),
+    ).toBe(false);
+    expect(
+      pageContains("/c/delivery/core/shipment/entity/parcel", shipment),
+    ).toBe(false);
+    expect(pageContains("/c/shop/oms/order/vo/money", money)).toBe(false);
+  });
+
+  it("still reads a four-segment path as an event page", () => {
+    const delivered = selectionFor("delivery.core.shipment.ShipmentDelivered");
+    expect(
+      pageContains("/c/delivery/core/shipment/shipment-delivered", delivered),
+    ).toBe(true);
+    expect(
+      pageContains("/c/delivery/core/shipment/shipment-delivered", dispatched),
+    ).toBe(false);
+  });
+});
+
+describe("selectionPath", () => {
+  it("sends an event to its own page and a shared type nowhere", () => {
+    expect(selectionPath(dispatched)).toBe(
+      "/c/delivery/core/shipment/shipment-dispatched",
+    );
+    expect(selectionPath(money)).toBeNull();
+  });
+});
+
+// Navigation keeps a selection only when the page it lands on can point at it.
+// These are the cases that decide whether the palette moves the reader.
+describe("pageContains across pages", () => {
+  const orderPlaced = selectionFor("shop.oms.order.OrderPlaced");
+  const oms = selectionFor("shop.oms");
+  const step = selectionFor("cart-checkout/s6");
+
+  it("keeps an event on the flow that carries it, and drops it elsewhere", () => {
+    expect(pageContains("/flows/oms-place-order-on-basket-checked-out", orderPlaced)).toBe(true);
+    expect(pageContains("/flows/shipment-tracking", orderPlaced)).toBe(false);
+  });
+
+  it("keeps a service on its own page and on its context page", () => {
+    expect(pageContains("/c/shop/oms", oms)).toBe(true);
+    expect(pageContains("/c/shop", oms)).toBe(true);
+    expect(pageContains("/c/payments", oms)).toBe(false);
+  });
+
+  // The rule the palette leans on: an event picked while its service page is
+  // open opens the panel, because the page already holds it.
+  it("keeps an event on the pages above it", () => {
+    expect(pageContains("/c/shop/oms", orderPlaced)).toBe(true);
+    expect(pageContains("/c/shop/oms/order", orderPlaced)).toBe(true);
+    expect(pageContains("/c/shop/pricing", orderPlaced)).toBe(false);
+  });
+
+  it("binds a step to its own flow", () => {
+    expect(pageContains("/flows/cart-checkout", step)).toBe(true);
+    expect(pageContains("/flows/auth-login", step)).toBe(false);
+  });
+
+  it("holds services and events on the dependency graph", () => {
+    expect(pageContains("/graph", oms)).toBe(true);
+    expect(pageContains("/graph", orderPlaced)).toBe(true);
+    expect(pageContains("/graph", step)).toBe(false);
+  });
+
+  it("holds nothing on the pages that draw no diagram", () => {
+    for (const path of ["/", "/flows", "/adrs", "/adrs/anything"]) {
+      expect(pageContains(path, oms), path).toBe(false);
+      expect(pageContains(path, orderPlaced), path).toBe(false);
+    }
+  });
+
+  it("ignores a query string and a hash when matching", () => {
+    expect(pageContains("/c/shop/oms?tab=consumes", oms)).toBe(true);
+    expect(pageContains("/c/shop/oms#sel=service:shop.oms", oms)).toBe(true);
+  });
+});
+
+describe("the registry pages", () => {
+  // A module page draws one module. It LINKS to the services that read it, and
+  // a page contains what it draws rather than everything it points at.
+  it("contains only the module whose page it is", () => {
+    const mine = { kind: "module" as const, id: "buf.build/acme/shop" };
+
+    // Resolution goes through the app's own catalog, which has no modules -
+    // so an id it cannot resolve is contained by nothing, anywhere.
+    expect(pageContains("/registry/acme-shop", mine)).toBe(false);
+    expect(pageContains("/c/shop/oms", mine)).toBe(false);
+  });
+
+  it("does not think a service page is a registry page", () => {
+    const service = { kind: "service" as const, id: "shop.oms" };
+
+    expect(pageContains("/registry", service)).toBe(false);
+    expect(pageContains("/registry/acme-shop", service)).toBe(false);
+  });
+});