@shortlink-org/portolan 0.1.0

package/src/lib/adr.ts

@@ -0,0 +1,68 @@
+// Pure derivations over the decision records. Same rule as derive.ts: nothing
+// here reads the DOM or the router, so every list an ADR page shows is testable.
+
+import type { Adr, AdrScope, Catalog } from "../catalog";
+import { byDateDesc } from "../catalog";
+
+/** "ADR-0007". The padded number is the name people use in prose and commits. */
+export function adrNumber(adr: Adr): string {
+  return `ADR-${String(adr.number).padStart(4, "0")}`;
+}
+
+/** Superseded and deprecated records are history: true, but no longer in force. */
+export function isCurrent(adr: Adr): boolean {
+  return adr.status !== "superseded" && adr.status !== "deprecated";
+}
+
+export function sortAdrs(adrs: Adr[]): Adr[] {
+  return [...adrs].sort(byDateDesc);
+}
+
+export function scopeLabel(scope: AdrScope): string {
+  switch (scope.kind) {
+    case "org":
+      return "org";
+    case "context":
+      return scope.context;
+    case "service":
+      return scope.service;
+  }
+}
+
+/**
+ * Does this record govern that service? An org-wide decision governs every
+ * service, a context-wide one governs the services inside it, and `relates`
+ * names services individually.
+ */
+export function adrCoversService(
+  adr: Adr,
+  serviceId: string,
+  contextId: string,
+): boolean {
+  if (adr.scope.kind === "org") return true;
+  if (adr.scope.kind === "service" && adr.scope.service === serviceId)
+    return true;
+  if (adr.scope.kind === "context" && adr.scope.context === contextId)
+    return true;
+  return (adr.relates.services ?? []).includes(serviceId);
+}
+
+/** Decisions governing a service, newest first. */
+export function adrsForService(
+  catalog: Catalog,
+  serviceId: string,
+  contextId: string,
+): Adr[] {
+  return sortAdrs(
+    catalog.adrs.filter((a) => adrCoversService(a, serviceId, contextId)),
+  );
+}
+
+/** The n newest accepted decisions, for the sidebar. */
+export function newestAccepted(catalog: Catalog, n: number): Adr[] {
+  return sortAdrs(catalog.adrs.filter((a) => a.status === "accepted")).slice(
+    0,
+    n,
+  );
+}
+

package/src/lib/api.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../data";
+import type { Service } from "../catalog";
+import {
+  declaredMethods,
+  interfaceDeclaring,
+  methodCount,
+  methodId,
+  methodNamed,
+  operationsExposedBy,
+  streamingKind,
+  unexposed,
+} from "./api";
+
+function auth(): Service {
+  const service = catalog.contexts
+    .find((c) => c.id === "auth")
+    ?.services.find((s) => s.slug === "auth");
+  if (!service) throw new Error("the auth service is not in the catalog");
+
+  return service;
+}
+
+describe("interfaceDeclaring", () => {
+  it("finds the interface a method belongs to", () => {
+    expect(interfaceDeclaring(auth(), "registerUser")?.id).toBe(
+      "auth.v1.Users",
+    );
+    expect(interfaceDeclaring(auth(), "login")?.id).toBe("auth.v1.Sessions");
+    expect(interfaceDeclaring(auth(), "nothing")).toBeUndefined();
+  });
+
+  it("writes a method the way the rest of the app writes one", () => {
+    expect(methodId(auth(), "registerUser")).toBe("auth.v1.Users/registerUser");
+  });
+});
+
+describe("operationsExposedBy", () => {
+  it("finds the operation an endpoint runs", () => {
+    const run = operationsExposedBy(auth(), "registerUser");
+    expect(run.map((r) => r.operation.id)).toEqual(["Register"]);
+    expect(run[0]?.aggregate.id).toBe("auth.auth.user");
+  });
+
+  // The change-password endpoint resolves the bearer token itself before it
+  // changes anything, so it has run two use cases - and they belong to two
+  // different aggregates.
+  it("finds every operation an endpoint runs, across aggregates", () => {
+    const run = operationsExposedBy(auth(), "changePassword");
+    expect(
+      run.map((r) => `${r.aggregate.slug}/${r.operation.id}`).sort(),
+    ).toEqual(["session/Validate", "user/ChangePassword"]);
+  });
+});
+
+describe("unexposed", () => {
+  // Both of these are deliberate. The service documents why there is no
+  // endpoint that checks a password without issuing a session, and the other
+  // is run by a policy reacting to an event rather than by any caller.
+  it("finds the operations nothing outside the service can reach", () => {
+    expect(
+      unexposed(auth())
+        .map((r) => r.operation.id)
+        .sort(),
+    ).toEqual([
+      // The lockout's three are asked by the credential check through a
+      // port, and the check itself by login: none of the four has a route of
+      // its own.
+      "Check",
+      "CheckCredentials",
+      "EndAfterCredentialChange",
+      "RecordFailure",
+      "RecordSuccess",
+    ]);
+  });
+});
+
+// The boundary between the two halves of an interface is BY NAME, and stayed
+// that way when a method stopped being a string: `Operation.exposedBy` names a
+// method, and so does a flow step's ref. That every assertion above passes
+// unmodified is the proof the boundary did not move.
+describe("methods, now that a method is more than a name", () => {
+  it("finds one method of one interface by name", () => {
+    const users = interfaceDeclaring(auth(), "registerUser");
+    if (!users) throw new Error("no interface");
+
+    expect(methodNamed(users, "registerUser")?.name).toBe("registerUser");
+    expect(methodNamed(users, "nothing")).toBeUndefined();
+  });
+
+  it("lists every method the service answers on, in catalog order", () => {
+    const declared = declaredMethods(auth());
+
+    expect(declared.length).toBe(methodCount(auth()));
+    expect(declared[0]?.provided.id).toBe("auth.v1.Users");
+    expect(declared.map((d) => d.method.name)).toContain("login");
+  });
+
+  it("counts across every interface, not just the first", () => {
+    const service = auth();
+
+    expect(methodCount(service)).toBe(
+      service.provides.reduce((n, p) => n + p.methods.length, 0),
+    );
+  });
+
+  // The catalog leaves unary out because it is the case not worth writing
+  // down; a reader deciding what to draw wants all four cases named.
+  it("names all four streaming shapes, unary included", () => {
+    expect(streamingKind({ name: "a" })).toBe("unary");
+    expect(streamingKind({ name: "a", streaming: "client" })).toBe("client");
+    expect(streamingKind({ name: "a", streaming: "server" })).toBe("server");
+    expect(streamingKind({ name: "a", streaming: "bidi" })).toBe("bidi");
+  });
+
+  it("counts nothing for a service that only listens", () => {
+    const silent: Service = { ...auth(), provides: [] };
+
+    expect(methodCount(silent)).toBe(0);
+    expect(declaredMethods(silent)).toEqual([]);
+  });
+});

package/src/lib/api.ts

@@ -0,0 +1,135 @@
+// The two halves of an interface, joined.
+//
+// An operation says which methods expose it, by name; an interface says which
+// methods it declares. Neither half knows the other, because they are read out
+// of different files by different generators - the handlers say what runs, the
+// document says what is offered - and they meet here, after the merge, which is
+// the first place both are present.
+
+import type {
+  Aggregate,
+  Operation,
+  RpcMethod,
+  RpcService,
+  Service,
+} from "../catalog";
+
+/**
+ * The interface that declares a method. Undefined when nothing this service
+ * offers carries that name, which the validator refuses in a catalog and is
+ * therefore a shape callers may ignore rather than one they must handle.
+ */
+export function interfaceDeclaring(
+  service: Service,
+  method: string,
+): RpcService | undefined {
+  return service.provides.find((provided) =>
+    provided.methods.some((declared) => declared.name === method),
+  );
+}
+
+/**
+ * A method by name, within one interface.
+ *
+ * By name rather than by index, because a name is what every other half of the
+ * catalog holds: `Operation.exposedBy` names one, a flow step's ref ends in
+ * one, and `rpcProviderByMethod` is keyed by one.
+ */
+export function methodNamed(
+  provided: RpcService,
+  name: string,
+): RpcMethod | undefined {
+  return provided.methods.find((method) => method.name === name);
+}
+
+export interface DeclaredMethod {
+  provided: RpcService;
+  method: RpcMethod;
+}
+
+/**
+ * Every method the service answers on, flat, in catalog order.
+ *
+ * Written once because the sidebar, the palette and three separate counts all
+ * want the same list, and four copies of one flatMap is how they drift.
+ */
+export function declaredMethods(service: Service): DeclaredMethod[] {
+  return service.provides.flatMap((provided) =>
+    provided.methods.map((method) => ({ provided, method })),
+  );
+}
+
+/** How many methods the service answers on, across every interface. */
+export function methodCount(service: Service): number {
+  return service.provides.reduce(
+    (n, provided) => n + provided.methods.length,
+    0,
+  );
+}
+
+/**
+ * How a method streams, as a value rather than as an absence.
+ *
+ * `undefined` is unary in the catalog because that is the case not worth
+ * writing down; a reader deciding what to draw wants the four cases named.
+ */
+export function streamingKind(
+  method: RpcMethod,
+): "unary" | "client" | "server" | "bidi" {
+  return method.streaming ?? "unary";
+}
+
+/** The interface method, written the way the rest of the app writes one. */
+export function methodId(service: Service, method: string): string {
+  const declaring = interfaceDeclaring(service, method);
+
+  return declaring ? `${declaring.id}/${method}` : method;
+}
+
+export interface ExposedOperation {
+  aggregate: Aggregate;
+  operation: Operation;
+}
+
+/**
+ * What a method actually runs, across every aggregate of the service.
+ *
+ * More than one is normal rather than a mistake: an endpoint that resolves a
+ * token before changing a password has run two use cases, and a page that
+ * showed only the second would be describing half of what happened.
+ */
+export function operationsExposedBy(
+  service: Service,
+  method: string,
+): ExposedOperation[] {
+  const out: ExposedOperation[] = [];
+
+  for (const aggregate of service.aggregates) {
+    for (const operation of aggregate.operations) {
+      if (operation.exposedBy?.includes(method)) {
+        out.push({ aggregate, operation });
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Operations nothing outside the service can reach.
+ *
+ * Not a defect on its own: a use case run by a policy rather than by a caller
+ * is unreachable on purpose, and so is one deliberately left off the API. It
+ * is worth being able to ask the question.
+ */
+export function unexposed(service: Service): ExposedOperation[] {
+  const out: ExposedOperation[] = [];
+
+  for (const aggregate of service.aggregates) {
+    for (const operation of aggregate.operations) {
+      if (!operation.exposedBy?.length) out.push({ aggregate, operation });
+    }
+  }
+
+  return out;
+}

package/src/lib/backlinks.test.ts

@@ -0,0 +1,330 @@
+import { describe, expect, it } from "vitest";
+import { catalog, index } from "../testing/estate";
+import { backlinkCount, backlinksFor, stepsInto } from "./backlinks";
+import type { BacklinkGroup, BacklinkTarget } from "./backlinks";
+import type { Kind } from "./kinds";
+
+function groups(target: BacklinkTarget): BacklinkGroup[] {
+  return backlinksFor(catalog, index, target);
+}
+
+function of(target: BacklinkTarget, kind: Kind) {
+  return groups(target).find((g) => g.kind === kind)?.links ?? [];
+}
+
+describe("stepsInto", () => {
+  it("numbers steps by their place in the whole flow, frames included", () => {
+    const steps = stepsInto(catalog, new Set(["shop.oms.order.OrderPlaced"]));
+    expect(steps.map((s) => `${s.flow.slug}#${s.stepId}`)).toEqual([
+      "checkout#s12",
+      "checkout#s14",
+      "checkout#s15",
+      "order-accepted#a2",
+      "order-accepted#a3",
+    ]);
+    expect(steps[0]?.number).toBe(12);
+  });
+
+  it("takes several events at once and still comes out in flow order", () => {
+    const steps = stepsInto(
+      catalog,
+      new Set([
+        "shop.oms.order.OrderPlaced",
+        "shop.oms.order.OrderCancelled",
+      ]),
+    );
+    const flows = steps.map((s) => s.flow.slug);
+    // Flows in catalog order, never interleaved.
+    expect([...new Set(flows)]).toEqual(
+      flows.filter((f, i) => flows[i - 1] !== f),
+    );
+  });
+});
+
+describe("an event", () => {
+  const target: BacklinkTarget = {
+    kind: "event",
+    id: "shop.oms.order.OrderPlaced",
+  };
+
+  it("is pointed at by its consumers, carrying their status", () => {
+    expect(of(target, "service").map((l) => [l.id, l.via, l.status])).toEqual([
+      ["payments.ledger", "consumes", "verified"],
+      ["shop.pricing", "consumes", "declared"],
+      ["analytics-sink", "consumes", "unresolved"],
+    ]);
+  });
+
+  it("names a consumer the catalog does not have, rather than dropping it", () => {
+    const ghost = of(target, "service").find((l) => l.id === "analytics-sink");
+    expect(ghost?.owner).toBe("not in the catalog");
+    expect(ghost?.context).toBeNull();
+  });
+
+  it("points at the step of a flow, not the top of it", () => {
+    expect(of(target, "flow").map((l) => `${l.id}#${l.at} ${l.via}`)).toEqual([
+      "checkout#s12 step 12",
+      "checkout#s14 step 14",
+      "checkout#s15 step 15",
+      "order-accepted#a2 step 2",
+      "order-accepted#a3 step 3",
+    ]);
+  });
+
+  it("lists the decisions that name it, and says which field named it", () => {
+    const adrs = of(
+      { kind: "event", id: "shop.cart.basket.BasketCheckedOut" },
+      "adr",
+    );
+    expect(adrs.map((l) => [l.id, l.name, l.via])).toEqual([
+      ["org.0002", "ADR-0002", "relates.events"],
+    ]);
+  });
+});
+
+describe("a service", () => {
+  const target: BacklinkTarget = { kind: "service", id: "shop.oms" };
+
+  it("is pointed at by its rpc callers — the half its own page never shows", () => {
+    const calls = of(target, "service").filter((l) =>
+      l.via.startsWith("calls"),
+    );
+    expect(calls.map((l) => `${l.id} ${l.via}`)).toEqual([
+      "shop.pricing calls shop.v1.Orders/GetOrder",
+      "payments.ledger calls shop.v1.Orders/GetOrder",
+      "delivery.core calls shop.v1.Orders/GetOrder",
+    ]);
+  });
+
+  it("says which event each listener listens to", () => {
+    const heard = of(target, "service").filter((l) =>
+      l.via.startsWith("consumes"),
+    );
+    expect(heard).toContainEqual(
+      expect.objectContaining({
+        id: "delivery.core",
+        via: "consumes OrderConfirmed",
+        status: "verified",
+      }),
+    );
+  });
+
+  it("counts a service that listens to two of its events twice, once per event", () => {
+    const ledger = of(target, "service").filter(
+      (l) => l.id === "payments.ledger" && l.via.startsWith("consumes"),
+    );
+    expect(ledger.map((l) => l.via)).toEqual([
+      "consumes OrderPlaced",
+      "consumes OrderCancelled",
+    ]);
+  });
+
+  it("takes only the decisions that name it — org-wide is not a backlink", () => {
+    const adrs = of(target, "adr");
+    expect(adrs.map((l) => [l.name, l.via])).toEqual([
+      ["ADR-0007", "scope"],
+      ["ADR-0003", "scope"],
+      ["ADR-0001", "relates.services"],
+    ]);
+  });
+
+  it("is not its own backlink", () => {
+    expect(of(target, "service").every((l) => l.id !== "shop.oms")).toBe(true);
+  });
+});
+
+describe("a context", () => {
+  const target: BacklinkTarget = { kind: "context", id: "shop" };
+
+  it("ignores traffic between its own services", () => {
+    // shop.pricing calls shop.oms and listens to it, but both sit inside.
+    expect(of(target, "service").every((l) => l.context !== "shop")).toBe(true);
+  });
+
+  it("keeps the callers from outside", () => {
+    expect(
+      of(target, "service")
+        .filter((l) => l.via.startsWith("calls"))
+        .map((l) => l.id),
+    ).toEqual(["payments.ledger", "delivery.core"]);
+  });
+
+  it("says which of its participants a flow actually runs through", () => {
+    const checkout = of(target, "flow").find((l) => l.id === "checkout");
+    // A store the context owns counts: a flow that reaches into it is a flow
+    // that depends on this context, whatever kind of participant it is.
+    expect(checkout?.via).toBe("shop.oms, oms-db, shop.pricing");
+  });
+});
+
+describe("an aggregate", () => {
+  const target: BacklinkTarget = { kind: "aggregate", id: "shop.oms.order" };
+
+  it("is reached through its events, and every row says which one", () => {
+    for (const link of of(target, "service")) {
+      expect(link.via).toMatch(/^consumes /);
+    }
+    for (const link of of(target, "flow")) {
+      expect(link.via).toMatch(/^step \d+ · /);
+    }
+  });
+
+  it("draws a decision naming two of its events once, not twice", () => {
+    const ids = of(
+      { kind: "aggregate", id: "payments.ledger.payment" },
+      "adr",
+    ).map((l) => l.id);
+    expect(ids.length).toBe(new Set(ids).size);
+  });
+});
+
+describe("a value object", () => {
+  const money: BacklinkTarget = { kind: "vo", id: "shop.oms.order.money" };
+
+  it("finds the other blocks that name the same shared type", () => {
+    const others = of(money, "vo").map((l) => l.id);
+    expect(others).toContain("shop.pricing.quote.money");
+    expect(others).toContain("payments.ledger.payment.money");
+    // Never itself.
+    expect(others).not.toContain("shop.oms.order.money");
+  });
+
+  it("says which fields carry the type, and in which event versions", () => {
+    const events = of(money, "event");
+    expect(events.length).toBeGreaterThan(0);
+    for (const link of events) expect(link.via).not.toBe("");
+    expect(events.some((l) => (l.versions?.length ?? 0) > 0)).toBe(true);
+  });
+
+  it("has nothing to find for an inline shape", () => {
+    const inline = catalog.contexts
+      .flatMap((c) => c.services)
+      .flatMap((s) => s.aggregates)
+      .flatMap((a) => a.valueObjects)
+      .find((b) => !b.ref);
+    if (!inline) throw new Error("no inline value object in the catalog");
+    expect(backlinkCount(groups({ kind: "vo", id: inline.id }))).toBe(0);
+  });
+});
+
+describe("an enum", () => {
+  const code: BacklinkTarget = { kind: "enum", id: "payments.ledger.payment.decline-code" };
+
+  it("finds the fields that switch on it, and says the match is by name", () => {
+    const events = of(code, "event");
+    expect(events.map((l) => l.id)).toContain("payments.ledger.payment.PaymentDeclined");
+    for (const link of events) {
+      expect(link.via).toContain("code");
+      expect(link.via).toContain("by name");
+    }
+  });
+
+  it("has nothing for a set the catalog lacks", () => {
+    expect(backlinkCount(groups({ kind: "enum", id: "x.y.z" }))).toBe(0);
+  });
+});
+
+describe("a flow", () => {
+  it("is pointed at only by the decisions that name it", () => {
+    const adrs = of({ kind: "flow", id: "checkout" }, "adr");
+    expect(adrs.map((l) => l.name).sort()).toEqual([
+      "ADR-0003",
+      "ADR-0004",
+      "ADR-0007",
+    ]);
+    for (const link of adrs) expect(link.via).toBe("relates.flows");
+  });
+});
+
+describe("a store", () => {
+  const target: BacklinkTarget = { kind: "store", id: "shop.oms.pg" };
+
+  it("is pointed at by the services that read it, and says so", () => {
+    const readers = of(target, "service");
+    expect(readers.map((l) => [l.id, l.via])).toContainEqual([
+      "delivery.core",
+      "reads",
+    ]);
+    expect(readers.some((l) => l.id === "shop.oms")).toBe(false);
+  });
+
+  it("names the aggregates its tables hold, once per table", () => {
+    const held = of(target, "aggregate");
+    expect(held.length).toBeGreaterThan(0);
+    for (const link of held) expect(link.via).toMatch(/^persisted in /);
+    expect(held.map((l) => l.id)).toContain("shop.oms.order");
+  });
+});
+
+describe("targets the catalog does not have", () => {
+  it("answer nothing rather than throwing", () => {
+    for (const kind of [
+      "context",
+      "service",
+      "aggregate",
+      "event",
+      "vo",
+      "flow",
+    ] as const) {
+      expect(backlinksFor(catalog, index, { kind, id: "nope" })).toEqual([]);
+    }
+  });
+
+  it("include decision records, whose incoming edges are their banners", () => {
+    expect(
+      backlinksFor(catalog, index, { kind: "adr", id: "org.0001" }),
+    ).toEqual([]);
+  });
+});
+
+describe("grouping", () => {
+  it("orders groups by how loudly they depend, services first", () => {
+    const kinds = groups({
+      kind: "event",
+      id: "shop.oms.order.OrderPlaced",
+    }).map((g) => g.kind);
+    expect(kinds).toEqual(["service", "flow"]);
+  });
+
+  it("counts every link across every group", () => {
+    const g = groups({ kind: "service", id: "shop.oms" });
+    expect(backlinkCount(g)).toBe(g.reduce((n, x) => n + x.links.length, 0));
+  });
+});
+
+describe("the word that names it", () => {
+  it("is a backlink on the thing the glossary names", () => {
+    const links = backlinksFor(catalog, index, {
+      kind: "aggregate",
+      id: "auth.auth.session",
+    });
+    const terms = links.find((g) => g.kind === "term");
+
+    expect(terms?.links).toHaveLength(1);
+    expect(terms?.links[0]?.name).toBe("Session");
+    expect(terms?.links[0]?.via).toBe("names it");
+  });
+
+  // Last group on the page. Every other row answers "who breaks when this
+  // changes"; this one answers "what is it called", which is read after.
+  it("comes after everything that depends on the thing", () => {
+    const links = backlinksFor(catalog, index, {
+      kind: "aggregate",
+      id: "auth.auth.session",
+    });
+
+    expect(links[links.length - 1]?.kind).toBe("term");
+  });
+
+  // Most of the estate. Only two contexts keep a glossary, and inside them the
+  // pairing is exact - so a page with no word on it is the ordinary page, and
+  // it says nothing rather than reporting a gap.
+  it("says nothing about a thing no word names", () => {
+    const links = backlinksFor(catalog, index, {
+      kind: "aggregate",
+      id: "payments.ledger.payment",
+    });
+
+    expect(links.some((g) => g.kind === "term")).toBe(false);
+  });
+});