@shortlink-org/portolan 0.1.0

package/src/peek/model.ts

@@ -0,0 +1,253 @@
+// What a peek says, for any id the selection model can resolve.
+//
+// A peek is the detail panel with everything but the first glance taken out:
+// what kind of thing this is, where it sits, two lines of what it is for, and
+// the three or four numbers a reader is weighing before deciding to click.
+// It is derived from the catalog on every hover rather than stored, for the
+// same reason the trail and the pins are: nothing here can go stale.
+//
+// Facts are `{label, value}` pairs and never sentences. The card lays them out
+// in one row, and a row of "3 consumers · v2 · 2 flows" is read in the time
+// a sentence takes to start.
+
+import { viewReads } from "../catalog";
+import { catalog, index } from "../data";
+import { methodCount } from "../lib/api";
+import { flowsForService, usesOfDef } from "../lib/derive";
+import type { Kind } from "../lib/kinds";
+import { flattenProse } from "../lib/palette";
+import { resolveSelection } from "../selection/model";
+
+export interface PeekFact {
+  /** True for "3 consumers": the number is read before its noun. */
+  countable?: true;
+  label: string;
+  value: string;
+}
+
+export interface Peek {
+  kind: Kind;
+  id: string;
+  /** What the card is headed with: a name, not an id. */
+  name: string;
+  /** For painting the icon; null for anything outside every context. */
+  contextId: string | null;
+  /** One line under the name saying what holds it. */
+  where: string;
+  /** Two lines at most, already flattened and trimmed; null when nothing was written. */
+  blurb: string | null;
+  facts: PeekFact[];
+}
+
+/** How much prose a card carries. About two lines of the card's width. */
+export const BLURB_CHARS = 160;
+
+/**
+ * The first `BLURB_CHARS` of a text, cut at a word and marked as cut. A blurb
+ * is a glance, and a glance that runs to a third line is a paragraph.
+ */
+export function blurbOf(markdown: string | undefined | null): string | null {
+  if (!markdown) return null;
+  // Headings go: a readme opens with the thing's own name, and the card has
+  // already said it once, in bold, on the line above.
+  const prose = flattenProse(markdown.replace(/^#{1,6}\s[^\n]*$/gm, " "));
+  if (!prose) return null;
+  if (prose.length <= BLURB_CHARS) return prose;
+  const cut = prose.slice(0, BLURB_CHARS);
+  const at = cut.lastIndexOf(" ");
+  return `${(at > BLURB_CHARS / 2 ? cut.slice(0, at) : cut).replace(/[,;:.]$/, "")}…`;
+}
+
+/** "3 consumers", "1 flow": a count and its noun agreeing. */
+export function count(n: number, noun: string, plural = `${noun}s`): PeekFact {
+  return { countable: true, label: n === 1 ? noun : plural, value: String(n) };
+}
+
+/**
+ * The peek for a catalog id, or null when the id resolves to nothing or to
+ * something a card has nothing to add to: a flow step is one line of a rail
+ * the reader is already looking at, and a bundle is a line on one canvas.
+ */
+export function peekOf(id: string): Peek | null {
+  const resolved = resolveSelection(id);
+  if (!resolved) return null;
+
+  switch (resolved.kind) {
+    case "context": {
+      const { context } = resolved;
+      return {
+        kind: "context",
+        id,
+        name: context.name,
+        contextId: context.id,
+        where: context.classification
+          ? `${context.classification} context`
+          : "bounded context",
+        blurb: blurbOf(context.summary),
+        facts: [
+          count(context.services.length, "service"),
+          count(
+            context.services.reduce((n, s) => n + s.aggregates.length, 0),
+            "aggregate",
+          ),
+        ],
+      };
+    }
+    case "service": {
+      const { service, context } = resolved;
+      const events = service.aggregates.reduce((n, a) => n + a.events.length, 0);
+      return {
+        kind: "service",
+        id,
+        name: service.name,
+        contextId: context.id,
+        where: `${context.name} · ${service.repo}/${service.path}`,
+        blurb: blurbOf(service.readme),
+        facts: [
+          count(service.aggregates.length, "aggregate"),
+          count(events, "event"),
+          count(methodCount(service), "method"),
+          count(flowsForService(catalog, service.id).length, "flow"),
+        ],
+      };
+    }
+    case "aggregate": {
+      const { aggregate, service, context } = resolved;
+      return {
+        kind: "aggregate",
+        id,
+        name: aggregate.name,
+        contextId: context.id,
+        where: `${service.name} · root ${aggregate.root}`,
+        blurb: blurbOf(aggregate.readme),
+        facts: [
+          count(aggregate.events.length, "event"),
+          count(aggregate.operations.length, "operation"),
+          count(aggregate.entities.length, "entity", "entities"),
+          count(aggregate.valueObjects.length, "value object"),
+        ],
+      };
+    }
+    case "event": {
+      const { event, aggregate, service, context } = resolved;
+      const latest = event.versions[event.versions.length - 1];
+      const flows = index.flowsByEvent.get(event.id) ?? [];
+      return {
+        kind: "event",
+        id,
+        name: event.name,
+        contextId: context.id,
+        where: `${service.name} · ${aggregate.name}`,
+        blurb: blurbOf(latest?.doc),
+        facts: [
+          { label: "version", value: latest?.version ?? "—" },
+          count(latest?.fields.length ?? 0, "field"),
+          count(event.consumers.length, "consumer"),
+          count(flows.length, "flow"),
+        ],
+      };
+    }
+    case "store": {
+      const { store, service, context } = resolved;
+      return {
+        kind: "store",
+        id,
+        name: store.name,
+        contextId: context.id,
+        where: `${store.kind} · owned by ${service.name}`,
+        blurb: null,
+        facts: [
+          count(store.tables.length, "table"),
+          count(store.views?.length ?? 0, "view"),
+          count(store.keyspaces?.length ?? 0, "keyspace"),
+        ].filter((f) => f.value !== "0" || f.label === "tables"),
+      };
+    }
+    case "table": {
+      const { table, store, context } = resolved;
+      const persists = table.persists?.aggregate
+        ? index.aggregateById.get(table.persists.aggregate)?.name
+        : null;
+      return {
+        kind: "table",
+        id,
+        name: table.name,
+        contextId: context.id,
+        where: `${store.name}${table.role ? ` · ${table.role}` : ""}`,
+        blurb: blurbOf(table.doc),
+        facts: [
+          count(table.columns.length, "column"),
+          count(table.indexes?.length ?? 0, "index", "indexes"),
+          ...(persists ? [{ label: "persists", value: persists }] : []),
+        ],
+      };
+    }
+    case "view": {
+      const { view, store, context } = resolved;
+      return {
+        kind: "view",
+        id,
+        name: view.name,
+        contextId: context.id,
+        where: `${store.name}${view.materialized ? " · materialized" : ""}`,
+        blurb: blurbOf(view.doc),
+        facts: [
+          count(view.columns.length, "column"),
+          count(viewReads(view).length, "source", "sources"),
+        ],
+      };
+    }
+    case "column": {
+      const { column, table, view, context } = resolved;
+      const facts: PeekFact[] = [{ label: "type", value: column.type }];
+      if (column.pk) facts.push({ label: "key", value: "primary" });
+      if (column.fk) facts.push({ label: "→", value: column.fk.table });
+      if (column.nullable) facts.push({ label: "nullable", value: "yes" });
+      return {
+        kind: view ? "view" : "table",
+        id,
+        name: column.name,
+        contextId: context.id,
+        where: `column of ${view?.name ?? table?.name ?? ""}`,
+        blurb: null,
+        facts,
+      };
+    }
+    case "value-object": {
+      const { def } = resolved;
+      const uses = usesOfDef(catalog, id);
+      return {
+        kind: "def",
+        id,
+        name: id,
+        contextId: null,
+        where: "shared type",
+        blurb: null,
+        facts: [
+          count(def.fields.length, "field"),
+          count(uses.events.length, "event"),
+        ],
+      };
+    }
+    case "module": {
+      const { module } = resolved;
+      return {
+        kind: "module",
+        id,
+        name: module.name,
+        contextId: null,
+        where: module.registry ? `buf module · ${module.registry}` : "buf module",
+        blurb: null,
+        facts: [
+          ...(module.owner ? [{ label: "owner", value: module.owner }] : []),
+          ...(module.commit
+            ? [{ label: "commit", value: module.commit.slice(0, 7) }]
+            : []),
+        ],
+      };
+    }
+    case "flow-step":
+    case "bundle":
+      return null;
+  }
+}

package/src/routes.test.ts

@@ -0,0 +1,222 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "./data";
+import { walkSteps } from "./catalog";
+import {
+  adrPath,
+  allCatalogPaths,
+  blockPath,
+  eventPath,
+  isRoutable,
+  paths,
+  servicePath,
+  tablePath,
+  viewPath,
+  enumPath,
+} from "./routes";
+import { parseSelectionHash } from "./selection/hash";
+import { allAggregates, allStores, allViews, enumsOf } from "./catalog";
+import { registryCatalog } from "./lib/scenarios";
+
+describe("routes", () => {
+  it("routes every URL the catalog can produce", () => {
+    const unroutable = allCatalogPaths(catalog).filter((p) => !isRoutable(p));
+    expect(unroutable).toEqual([]);
+  });
+
+  it("never puts a dotted id in a URL segment", () => {
+    for (const path of allCatalogPaths(catalog)) {
+      const segments = path.split("/").filter(Boolean);
+      // the context segment is a plain id; service/aggregate/event are slugs
+      for (const segment of segments.slice(2)) {
+        expect(segment, `dotted segment in ${path}`).not.toContain(".");
+      }
+    }
+  });
+
+  it("resolves every event referenced by a flow step to a page", () => {
+    for (const flow of catalog.flows) {
+      for (const step of walkSteps(flow.steps)) {
+        if (step.kind !== "event" || !step.ref) continue;
+        const path = eventPath(step.ref);
+        expect(path, `${flow.slug}/${step.id} -> ${step.ref}`).not.toBeNull();
+        expect(isRoutable(path as string)).toBe(true);
+      }
+    }
+  });
+
+  it("resolves every flow participant that is a catalog service", () => {
+    for (const flow of catalog.flows) {
+      for (const participant of flow.participants) {
+        if (participant.kind !== "service") continue;
+        const path = servicePath(participant.id);
+        expect(
+          path,
+          `${flow.slug} participant ${participant.id}`,
+        ).not.toBeNull();
+      }
+    }
+  });
+
+  it("routes every value object and entity, behind its own literal segment", () => {
+    for (const aggregate of allAggregates(catalog)) {
+      for (const block of [...aggregate.valueObjects, ...aggregate.entities]) {
+        const path = blockPath(block.id);
+        expect(path, block.id).not.toBeNull();
+        expect(isRoutable(path as string), path as string).toBe(true);
+      }
+    }
+    expect(blockPath("shop.oms.order.money")).toBe(
+      "/c/shop/oms/order/vo/money",
+    );
+    expect(blockPath("shop.oms.order.line")).toBe(
+      "/c/shop/oms/order/entity/line",
+    );
+  });
+
+  it("routes every enum, behind its own literal segment", () => {
+    for (const aggregate of allAggregates(catalog)) {
+      for (const item of enumsOf(aggregate)) {
+        const path = enumPath(item.id);
+        expect(path, item.id).not.toBeNull();
+        expect(isRoutable(path as string), path as string).toBe(true);
+      }
+    }
+    expect(enumPath("shop.oms.order.status")).toBe(
+      "/c/shop/oms/order/enum/status",
+    );
+    expect(enumPath("shop.oms.order.nowhere")).toBeNull();
+  });
+
+  // Both are five segments deep, so nothing may fall through to the event route.
+  it("keeps block pages and event pages apart", () => {
+    expect(isRoutable("/c/shop/oms/order/vo/money")).toBe(true);
+    expect(isRoutable("/c/shop/oms/order/order-placed")).toBe(true);
+    expect(isRoutable("/c/shop/oms/order/vo")).toBe(true); // an event slug "vo"
+    expect(isRoutable("/c/shop/oms/order/vo/money/extra")).toBe(false);
+  });
+
+  it("returns null rather than a broken link for unknown ids", () => {
+    expect(servicePath("analytics-sink")).toBeNull();
+    expect(eventPath("nope.nope.Nope")).toBeNull();
+    expect(adrPath("shop.oms.0099")).toBeNull();
+    expect(blockPath("shop.oms.order.doubloons")).toBeNull();
+  });
+
+  it("routes every decision record, by slug rather than by id", () => {
+    for (const adr of catalog.adrs) {
+      const path = adrPath(adr.id);
+      expect(path, adr.id).toBe(`/adrs/${adr.slug}`);
+      expect(isRoutable(path as string)).toBe(true);
+    }
+    expect(isRoutable("/adrs")).toBe(true);
+  });
+
+  it("links every supersession to a routable page", () => {
+    for (const adr of catalog.adrs) {
+      for (const id of [adr.supersededBy, ...(adr.supersedes ?? [])]) {
+        if (!id) continue;
+        expect(adrPath(id), `${adr.id} -> ${id}`).not.toBeNull();
+      }
+    }
+  });
+
+  it("opens a view on the canvas of the store that declares it", () => {
+    for (const view of allViews(catalog)) {
+      const path = viewPath(view.id);
+      expect(path, view.id).not.toBeNull();
+      expect(isRoutable(path as string), path as string).toBe(true);
+    }
+    expect(viewPath("payments.ledger.pg.v_payment_state")).toBe(
+      "/c/payments/ledger/data/pg#sel=view:payments.ledger.pg.v_payment_state",
+    );
+    // A view is not a table and vice versa, so neither answers for the other.
+    expect(viewPath("shop.oms.pg.orders")).toBeNull();
+    expect(tablePath("payments.ledger.pg.v_payment_state")).toBeNull();
+  });
+
+  it("carries a view through the hash as a view", () => {
+    const link = viewPath("delivery.core.pg.mv_route_load") as string;
+    expect(parseSelectionHash(link.slice(link.indexOf("#")))).toEqual({
+      kind: "view",
+      id: "delivery.core.pg.mv_route_load",
+    });
+  });
+
+  it("has a store for every view, so no view is orphaned", () => {
+    const stores = new Set(allStores(catalog).map((s) => s.id));
+    for (const view of allViews(catalog)) {
+      expect(stores.has(view.id.split(".").slice(0, -1).join("."))).toBe(true);
+    }
+  });
+
+  it("ignores query strings when matching routes", () => {
+    expect(isRoutable("/c/shop/oms?tab=consumes")).toBe(true);
+    expect(isRoutable("/nope/nope/nope/nope/nope")).toBe(false);
+  });
+
+  it("routes the build settings page", () => {
+    expect(paths.settings()).toBe("/settings");
+    expect(isRoutable(paths.settings())).toBe(true);
+    expect(allCatalogPaths(catalog)).toContain(paths.settings());
+  });
+
+  it("routes the runtime catalog diff", () => {
+    expect(paths.changes()).toBe("/changes");
+    expect(isRoutable(`${paths.changes()}?base=main&head=feature`)).toBe(true);
+    expect(allCatalogPaths(catalog)).toContain(paths.changes());
+  });
+
+  it("gives every external contract one routable page", () => {
+    for (const external of catalog.externals ?? []) {
+      const path = paths.external(external.slug);
+      expect(path).toBe(`/externals/${external.slug}`);
+      expect(isRoutable(path)).toBe(true);
+      expect(allCatalogPaths(catalog)).toContain(path);
+    }
+  });
+
+  it("builds deep links to steps, carrying the step as a selection", () => {
+    const link = paths.flowStep("cart-checkout", "s6");
+    expect(link).toBe("/flows/cart-checkout#sel=flow-step:cart-checkout%2Fs6");
+    expect(isRoutable(link)).toBe(true);
+    expect(parseSelectionHash(link.slice(link.indexOf("#")))).toEqual({
+      kind: "flow-step",
+      id: "cart-checkout/s6",
+    });
+  });
+});
+
+describe("registry routes", () => {
+  const registry = registryCatalog();
+
+  it("routes every module path the catalog can produce", () => {
+    const unroutable = allCatalogPaths(registry).filter((p) => !isRoutable(p));
+
+    expect(unroutable).toEqual([]);
+  });
+
+  it("puts a module at one URL, keyed by its slug", () => {
+    expect(paths.module("acme-shop")).toBe("/registry/acme-shop");
+    expect(paths.registry()).toBe("/registry");
+  });
+
+  // A module slug is one segment. A dotted or slashed one would break the
+  // assertion above about URL segments, and would make `/registry/:module`
+  // stop matching.
+  it("never lets a module slug carry a dot or a slash", () => {
+    for (const module of registry.modules ?? []) {
+      expect(module.slug, module.id).not.toContain(".");
+      expect(module.slug, module.id).not.toContain("/");
+    }
+  });
+
+  it("refuses a path with too few or too many segments", () => {
+    expect(isRoutable("/registry")).toBe(true);
+    expect(isRoutable("/registry/acme-shop")).toBe(true);
+    expect(isRoutable("/registry/acme-shop/extra")).toBe(false);
+  });
+
+  it("lists /registry even for an estate that has published nothing", () => {
+    expect(allCatalogPaths(catalog)).toContain("/registry");
+  });
+});