@shortlink-org/portolan 0.1.0

package/src/lib/export-canvas.ts

@@ -0,0 +1,37 @@
+// A React Flow viewport, saved as a picture.
+//
+// The viewport is captured at its own size rather than the box's, so the file
+// holds the whole drawing however far it has been panned. Every canvas in the
+// app - the flow, the ER schema, the dependency graph, the context map - goes
+// out through here, so a picture of one looks like a picture of another.
+
+import { toPng, toSvg } from "html-to-image";
+import { artifactFilename } from "./export-file";
+
+export type ImageKind = "png" | "svg";
+
+/** The element html-to-image should capture: the pannable layer of a canvas. */
+export function viewportOf(root: Element | null | undefined): HTMLElement | null {
+  return root?.querySelector<HTMLElement>(".react-flow__viewport") ?? null;
+}
+
+/**
+ * Render the viewport and hand it to the browser as a download. Resolves to
+ * the file name it went out under, so the caller can say so.
+ */
+export async function saveCanvasImage(
+  viewport: HTMLElement,
+  name: string,
+  kind: ImageKind,
+): Promise<string> {
+  const render = kind === "png" ? toPng : toSvg;
+  const url = await render(viewport, {
+    backgroundColor: getComputedStyle(document.body).backgroundColor,
+    ...(kind === "png" ? { pixelRatio: 2 } : {}),
+  });
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = artifactFilename(name, kind);
+  a.click();
+  return a.download;
+}

package/src/lib/export-file.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import type { BuildInfo } from "./build-info";
+import { artifactFilename } from "./export-file";
+
+const info = (values: Partial<BuildInfo>): BuildInfo => ({
+  commit: "",
+  shortCommit: "",
+  branch: "",
+  builtAt: "",
+  commitUrl: "",
+  buildUrl: "",
+  buildNumber: "",
+  dirty: false,
+  repoUrl: "",
+  ...values,
+});
+
+describe("artifactFilename", () => {
+  it("prefers the commit and sanitizes the artifact name", () => {
+    expect(artifactFilename("checkout / happy path", "svg", info({ shortCommit: "abc1234", branch: "main" }))).toBe(
+      "checkout-happy-path-abc1234.svg",
+    );
+  });
+
+  it("uses a sanitized branch and safe fallbacks", () => {
+    expect(artifactFilename("///", ".png", info({ branch: "feature/export v2" }))).toBe(
+      "artifact-feature-export-v2.png",
+    );
+  });
+});

package/src/lib/export-file.ts

@@ -0,0 +1,20 @@
+import { buildInfo } from "./build-info";
+import type { BuildInfo } from "./build-info";
+
+function safePart(value: string, fallback: string): string {
+  const safe = value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return safe || fallback;
+}
+
+/** A reproducible export name that identifies both the artifact and its catalog revision. */
+export function artifactFilename(
+  name: string,
+  extension: string,
+  info: BuildInfo = buildInfo,
+): string {
+  const revision = info.shortCommit || info.branch || "catalog";
+  return `${safePart(name, "artifact")}-${safePart(revision, "catalog")}.${safePart(extension.replace(/^\./, ""), "bin")}`;
+}

package/src/lib/flow-tree.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from "vitest";
+import { catalog } from "../testing/estate";
+import type { Flow } from "../catalog";
+import {
+  GROUP_SHOW_HEAD,
+  flowEntry,
+  flowHealth,
+  flowOwner,
+  groupFlowsByOwner,
+  reachDots,
+  statusCounts,
+  visibleEntries,
+} from "./flow-tree";
+
+const bySlug = (slug: string): Flow => {
+  const flow = catalog.flows.find((f) => f.slug === slug);
+  if (!flow) throw new Error(`no flow ${slug}`);
+  return flow;
+};
+
+describe("flowOwner", () => {
+  it("reads the owner off the flow rather than working it out", () => {
+    // Every flow states the context it belongs to, because whatever derived it
+    // read that context's tree to find it. Nothing here infers.
+    expect(flowOwner(bySlug("checkout"))).toBe("shop");
+    expect(flowOwner(bySlug("gateway-webhook"))).toBe("payments");
+    expect(flowOwner(bySlug("shipment-tracking"))).toBe("delivery");
+  });
+
+  it("does not fall back to the lanes when a flow names no owner", () => {
+    // The first service lane would happily supply one. Guessing here is what
+    // the validator exists to stop, so the flow comes back unowned and the
+    // tree files it as a defect.
+    const unowned = { ...bySlug("checkout"), owner: undefined } as unknown as Flow;
+    expect(flowOwner(unowned)).toBeNull();
+  });
+});
+
+describe("flowHealth", () => {
+  it("is red the moment any step is unresolved", () => {
+    expect(flowHealth(bySlug("checkout"))).toBe("unresolved");
+    expect(flowHealth(bySlug("order-cancelled"))).toBe("unresolved");
+    expect(flowHealth(bySlug("shipment-tracking"))).toBe("unresolved");
+  });
+
+  it("is declared while some hop has not been seen running", () => {
+    // Written by hand from a design doc: every hop resolves, none observed.
+    expect(flowHealth(bySlug("refund-requested"))).toBe("declared");
+    // Pinned by a test on three of its four branches; the adopt branch is
+    // the one nobody covers, and one unseen message is enough.
+    expect(flowHealth(bySlug("gateway-webhook"))).toBe("declared");
+  });
+
+  it("is verified once every call in and every message has been seen", () => {
+    // order-accepted is pinned by an integration test end to end; the auth
+    // flows by the recording in examples/auth/telemetry, which shows the
+    // request arriving and the events leaving. The store calls between stay
+    // declared, and do not hold the flow back: a query having run is not the
+    // claim the code makes about the repository method.
+    expect(flowHealth(bySlug("order-accepted"))).toBe("verified");
+    expect(flowHealth(bySlug("auth-register-user"))).toBe("verified");
+    expect(flowHealth(bySlug("auth-change-password"))).toBe("verified");
+  });
+
+  it("is not verified by store calls alone", () => {
+    const only = { ...bySlug("auth-get-user"), steps: bySlug("auth-get-user").steps.slice(1) } as Flow;
+    // Only the ByID call is left, and a call is never a hop a trace vouches for.
+    expect(flowHealth(only)).toBe("declared");
+  });
+
+  it("counts steps by status", () => {
+    expect(statusCounts(bySlug("auth-login"))).toEqual({ verified: 2, declared: 14, unresolved: 1 });
+  });
+});
+
+describe("flowEntry", () => {
+  it("excludes the owner from the reach, so the dots say where else it goes", () => {
+    const entry = flowEntry(bySlug("checkout"));
+    expect(entry.reach).not.toContain("shop");
+    expect(entry.reach).toEqual(["payments", "delivery"]);
+  });
+});
+
+describe("groupFlowsByOwner", () => {
+  const groups = groupFlowsByOwner(catalog.flows);
+
+  it("files every flow under a context and leaves none unowned", () => {
+    expect(groups.map((g) => g.owner)).not.toContain(null);
+    const total = groups.reduce((n, g) => n + g.entries.length, 0);
+    expect(total).toBe(catalog.flows.length);
+  });
+
+  it("orders groups by how many flows they hold", () => {
+    expect(
+      groups.map((g) => [g.owner, g.entries.length] as const),
+    ).toEqual([
+      ["shop", 11],
+      ["auth", 7],
+      ["delivery", 1],
+      ["payments", 1],
+    ]);
+  });
+
+  it("puts the broken flows at the top of their group", () => {
+    const shop = groups.find((g) => g.owner === "shop");
+    if (!shop) throw new Error("no shop group");
+    // Two hand-written flows with a hop nobody resolves; then the ones every
+    // hop of which resolves but none has been seen running, cart's checkout
+    // among them because its call to pricing is answered by a stand-in; then
+    // the ones the recordings proved.
+    expect(shop.entries.map((e) => e.health)).toEqual([
+      "unresolved",
+      "unresolved",
+      "declared",
+      "declared",
+      "declared",
+      "verified",
+      "verified",
+      "verified",
+      "verified",
+      "verified",
+      "verified",
+    ]);
+    // Red first, then name: the two unresolved flows are alphabetical.
+    expect(shop.entries.slice(0, 2).map((e) => e.flow.name)).toEqual([
+      "Checkout",
+      "Order cancelled",
+    ]);
+  });
+
+  it("sends the unowned group to the end, where it reads as a defect", () => {
+    const orphan = {
+      ...bySlug("checkout"),
+      id: "flow.orphan",
+      slug: "orphan",
+      owner: undefined,
+    } as unknown as Flow;
+    const withOrphan = groupFlowsByOwner([orphan, ...catalog.flows]);
+    expect(withOrphan[withOrphan.length - 1]?.owner).toBeNull();
+  });
+});
+
+describe("visibleEntries", () => {
+  const entries = (n: number) =>
+    Array.from({ length: n }, (_, i) => ({
+      ...flowEntry(bySlug("checkout")),
+      flow: { ...bySlug("checkout"), slug: `f${i}` },
+    }));
+
+  it("lists a group whole while it still reads as a list", () => {
+    const eight = entries(8);
+    expect(visibleEntries(eight)).toEqual({ shown: eight, hidden: 0 });
+  });
+
+  it("stops listing past the limit and says how many it stopped at", () => {
+    const nine = entries(9);
+    const { shown, hidden } = visibleEntries(nine);
+    expect(shown).toHaveLength(GROUP_SHOW_HEAD);
+    expect(hidden).toBe(4);
+  });
+});
+
+describe("reachDots", () => {
+  it("draws every context when three or fewer", () => {
+    expect(reachDots(["a", "b", "c"])).toEqual({
+      dots: ["a", "b", "c"],
+      more: 0,
+    });
+  });
+
+  it("counts the rest rather than drawing an unreadable row of dots", () => {
+    expect(reachDots(["a", "b", "c", "d", "e"])).toEqual({
+      dots: ["a", "b", "c"],
+      more: 2,
+    });
+  });
+});

package/src/lib/flow-tree.ts

@@ -0,0 +1,160 @@
+// Who a flow belongs to, and how far it can be trusted.
+//
+// The sidebar files flows under a context rather than listing them flat,
+// because "which of our flows cross into payments" is a question about the
+// estate and "how many flows does shop own" is a question about a team. The
+// owner is never guessed: whatever derived the flow already knew whose tree it
+// read, and this module only reads the answer back out.
+//
+// Nothing here reads the DOM or the router, so every group, dot and count the
+// tree draws can be asserted in a test.
+
+import type { Flow, Status } from "../catalog";
+import { flowContexts, walkSteps } from "../catalog";
+
+/**
+ * How far a flow can be believed, in one word.
+ *
+ * Three states. A flow read out of source is in one of two: either every step
+ * resolves, or one points at something the catalog does not have. The third
+ * is reached only by a recording of the system running - a verifier that saw
+ * the hops happen - and it is held to the hops a trace can show: the call in,
+ * and every message between services. A `call` on a store is never raised by
+ * a trace, because a query having run is not the claim the code makes, so a
+ * flow whose every rpc and event is verified is as verified as a flow gets.
+ */
+export type FlowHealth = "verified" | "declared" | "unresolved";
+
+/** Order of attention: a broken flow first, a proven one last. */
+const HEALTH_RANK: Record<FlowHealth, number> = {
+  unresolved: 0,
+  declared: 1,
+  verified: 2,
+};
+
+export const FLOW_HEALTH_NOTE: Record<FlowHealth, string> = {
+  unresolved: "a step in this flow points at something the catalog does not have",
+  declared: "every step resolves to something the catalog has; none has been seen running",
+  verified: "every call in and every message between services has been seen running",
+};
+
+export function flowHealth(flow: Flow): FlowHealth {
+  const steps = walkSteps(flow.steps);
+  const statuses: Status[] = steps.map((s) => s.status);
+  if (statuses.some((s) => s === "unresolved")) return "unresolved";
+  const hops = steps.filter((s) => s.kind !== "call");
+  if (hops.length > 0 && hops.every((s) => s.status === "verified"))
+    return "verified";
+  return "declared";
+}
+
+/** How many steps of each status, for a card or a row that counts rather than dots. */
+export function statusCounts(flow: Flow): Record<Status, number> {
+  const counts: Record<Status, number> = { verified: 0, declared: 0, unresolved: 0 };
+  for (const step of walkSteps(flow.steps)) counts[step.status] += 1;
+  return counts;
+}
+
+/**
+ * The context a flow belongs to, or null when the catalog does not say.
+ *
+ * Read off the flow, never worked out from it. A flow that names no owner is a
+ * broken extraction, not a flow that belongs wherever its first participant
+ * happens to sit - so it comes back null and the tree shows it rather than
+ * filing it somewhere plausible.
+ */
+export function flowOwner(flow: Flow): string | null {
+  return flow.owner ?? null;
+}
+
+export interface FlowEntry {
+  flow: Flow;
+  health: FlowHealth;
+  /** Contexts the flow crosses beyond the one that owns it, in lane order. */
+  reach: string[];
+}
+
+export interface FlowGroup {
+  /** Context id, or null for the group of flows nothing claims. */
+  owner: string | null;
+  entries: FlowEntry[];
+}
+
+export function flowEntry(flow: Flow): FlowEntry {
+  const owner = flowOwner(flow);
+  return {
+    flow,
+    health: flowHealth(flow),
+    reach: flowContexts(flow).filter((c) => c !== owner),
+  };
+}
+
+/**
+ * Flows filed under their owner. Groups are ordered by how many flows they
+ * hold, so the context the estate does most of its work in is the one at the
+ * top; the unowned group is always last, because it is a defect report rather
+ * than a place.
+ *
+ * Inside a group the order is by health and then by name: a broken flow is the
+ * one worth opening, and everything below it is alphabetical so a reader can
+ * find a name they already know.
+ */
+export function groupFlowsByOwner(flows: Flow[]): FlowGroup[] {
+  const byOwner = new Map<string | null, FlowEntry[]>();
+  for (const flow of flows) {
+    const entry = flowEntry(flow);
+    const owner = flowOwner(flow);
+    const list = byOwner.get(owner);
+    if (list) list.push(entry);
+    else byOwner.set(owner, [entry]);
+  }
+
+  const groups: FlowGroup[] = [...byOwner].map(([owner, entries]) => ({
+    owner,
+    entries: [...entries].sort(
+      (a, b) =>
+        HEALTH_RANK[a.health] - HEALTH_RANK[b.health] ||
+        a.flow.name.localeCompare(b.flow.name),
+    ),
+  }));
+
+  groups.sort((a, b) => {
+    if (a.owner === null) return 1;
+    if (b.owner === null) return -1;
+    return b.entries.length - a.entries.length || a.owner.localeCompare(b.owner);
+  });
+  return groups;
+}
+
+/**
+ * How many flows a group shows before it stops listing and starts counting.
+ * Past this the tree is no longer something a reader scans - the index page
+ * is, and the last row says so.
+ */
+const GROUP_SHOW_LIMIT = 8;
+export const GROUP_SHOW_HEAD = 5;
+
+/** The rows a group actually draws, and how many it is standing in for. */
+export function visibleEntries(entries: FlowEntry[]): {
+  shown: FlowEntry[];
+  hidden: number;
+} {
+  if (entries.length <= GROUP_SHOW_LIMIT) {
+    return { shown: entries, hidden: 0 };
+  }
+  return {
+    shown: entries.slice(0, GROUP_SHOW_HEAD),
+    hidden: entries.length - GROUP_SHOW_HEAD,
+  };
+}
+
+/** Up to three reach dots, and what the "+n" after them stands for. */
+const REACH_DOTS = 3;
+
+export function reachDots(reach: string[]): {
+  dots: string[];
+  more: number;
+} {
+  if (reach.length <= REACH_DOTS) return { dots: reach, more: 0 };
+  return { dots: reach.slice(0, REACH_DOTS), more: reach.length - REACH_DOTS };
+}

package/src/lib/forge-refs.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import type { ForgeRef } from "./github-catalog";
+import { compareVersionsDesc, findRef, parseVersion, sortRefs } from "./forge-refs";
+
+const ref = (name: string, kind: ForgeRef["kind"] = "branch"): ForgeRef => ({
+  name, kind, commit: "a".repeat(40), protected: false,
+});
+
+describe("parseVersion", () => {
+  it("reads a version out of the usual tag spellings", () => {
+    expect(parseVersion("v1.2.3")).toEqual({ parts: [1, 2, 3], pre: "" });
+    expect(parseVersion("release-2.0")).toEqual({ parts: [2, 0], pre: "" });
+    expect(parseVersion("1.0.0-rc.1")).toEqual({ parts: [1, 0, 0], pre: "rc.1" });
+    expect(parseVersion("nightly")).toBeNull();
+  });
+});
+
+describe("compareVersionsDesc", () => {
+  it("puts the newest first and a prerelease before its release", () => {
+    const sorted = ["v1.2.0", "v1.10.0", "v1.2.0-rc.1", "v1.9.3"].sort(compareVersionsDesc);
+    expect(sorted).toEqual(["v1.10.0", "v1.9.3", "v1.2.0", "v1.2.0-rc.1"]);
+  });
+
+  it("keeps tags that are not versions after those that are", () => {
+    expect(["nightly", "v0.1.0", "archive"].sort(compareVersionsDesc)).toEqual(["v0.1.0", "nightly", "archive"]);
+  });
+});
+
+describe("sortRefs", () => {
+  it("leads with the current branch and main, then names, then tags newest first", () => {
+    const sorted = sortRefs([
+      ref("v1.0.0", "tag"), ref("feature/b"), ref("main"), ref("v2.0.0", "tag"), ref("feature/a"), ref("release"),
+    ], "release");
+    expect(sorted.map((r) => r.name)).toEqual(["release", "main", "feature/a", "feature/b", "v2.0.0", "v1.0.0"]);
+  });
+
+  it("does not let a tag named like the current branch jump the queue", () => {
+    const sorted = sortRefs([ref("main", "tag"), ref("dev"), ref("main")], "main");
+    expect(sorted.map((r) => r.kind)).toEqual(["branch", "branch", "tag"]);
+  });
+});
+
+describe("findRef", () => {
+  it("prefers the branch when a tag shares its name", () => {
+    const refs = [ref("v1", "tag"), ref("v1")];
+    expect(findRef(refs, "v1")?.kind).toBe("branch");
+    expect(findRef([ref("v1", "tag")], "v1")?.kind).toBe("tag");
+    expect(findRef(refs, "v2")).toBeUndefined();
+  });
+});

package/src/lib/forge-refs.ts

@@ -0,0 +1,60 @@
+// The order a reader picks a comparison head in, and how a name is resolved.
+//
+// Branches are what is being worked on and tags are what was shipped, and
+// they read differently: a branch list is scanned by name, a tag list from the
+// newest release down. So branches sort by name after the two a reader
+// reaches for first - the catalog's own branch, then main - and tags sort by
+// version, highest first, with anything that is not a version after them.
+
+import type { ForgeRef } from "./github-catalog";
+
+type Version = { parts: number[]; pre: string };
+
+/** `v1.2.3`, `1.2`, `release-2.0.1-rc.1` as numbers, or null when it is not one. */
+export function parseVersion(name: string): Version | null {
+  const m = /(\d+(?:\.\d+)*)(?:-([0-9A-Za-z.-]+))?$/.exec(name);
+  if (!m) return null;
+  return { parts: m[1]!.split(".").map(Number), pre: m[2] ?? "" };
+}
+
+/** Newest first. A prerelease comes before the release it precedes. */
+export function compareVersionsDesc(a: string, b: string): number {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) {
+    if (va) return -1;
+    if (vb) return 1;
+    return b.localeCompare(a);
+  }
+  const length = Math.max(va.parts.length, vb.parts.length);
+  for (let i = 0; i < length; i++) {
+    const d = (vb.parts[i] ?? 0) - (va.parts[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  if (va.pre && !vb.pre) return 1;
+  if (!va.pre && vb.pre) return -1;
+  return vb.pre.localeCompare(va.pre) || b.localeCompare(a);
+}
+
+/** The picker's order: current, main, other branches by name, tags newest first. */
+export function sortRefs(refs: ForgeRef[], current: string): ForgeRef[] {
+  const rank = (ref: ForgeRef) =>
+    ref.name === current && ref.kind === "branch" ? 0
+    : ref.name === "main" && ref.kind === "branch" ? 1
+    : ref.kind === "branch" ? 2
+    : 3;
+  return [...refs].sort((a, b) => {
+    const d = rank(a) - rank(b);
+    if (d !== 0) return d;
+    return a.kind === "tag" ? compareVersionsDesc(a.name, b.name) : a.name.localeCompare(b.name);
+  });
+}
+
+/**
+ * The ref a URL names. A tag and a branch may share a name, and the branch
+ * wins, because that is what git itself resolves a bare name to.
+ */
+export function findRef(refs: ForgeRef[], name: string): ForgeRef | undefined {
+  return refs.find((ref) => ref.name === name && ref.kind === "branch")
+    ?? refs.find((ref) => ref.name === name);
+}

package/src/lib/format.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { absoluteTime, plural, relativeTime } from "./format";
+
+const now = new Date("2026-08-31T12:00:00Z");
+
+describe("relativeTime", () => {
+  it("collapses recent times", () => {
+    expect(relativeTime("2026-08-31T11:59:50Z", now)).toBe("just now");
+  });
+  it("counts minutes, hours, days", () => {
+    expect(relativeTime("2026-08-31T11:00:00Z", now)).toBe("1 hour ago");
+    expect(relativeTime("2026-08-29T12:00:00Z", now)).toBe("2 days ago");
+  });
+  it("passes through unparseable input", () => {
+    expect(relativeTime("not-a-date", now)).toBe("not-a-date");
+  });
+});
+
+describe("absoluteTime", () => {
+  it("renders a compact UTC stamp", () => {
+    expect(absoluteTime("2026-08-29T09:14:22Z")).toBe("2026-08-29 09:14:22Z");
+  });
+});
+
+describe("plural", () => {
+  it("keeps the singular at exactly one", () => {
+    expect(plural(1, "service")).toBe("service");
+    expect(plural(0, "service")).toBe("services");
+    expect(plural(2, "service")).toBe("services");
+  });
+  it("takes an irregular plural", () => {
+    expect(plural(1, "entity", "entities")).toBe("entity");
+    expect(plural(3, "entity", "entities")).toBe("entities");
+  });
+});

package/src/lib/format.ts

@@ -0,0 +1,64 @@
+/** "3 days ago" style, coarse on purpose: precision here is noise. */
+export function relativeTime(iso: string, now: Date = new Date()): string {
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return iso;
+  const seconds = Math.round((now.getTime() - then) / 1000);
+  const future = seconds < 0;
+  const abs = Math.abs(seconds);
+  const units: [number, string][] = [
+    [60, "second"],
+    [3600, "minute"],
+    [86400, "hour"],
+    [604800, "day"],
+    [2629800, "week"],
+    [31557600, "month"],
+    [Number.POSITIVE_INFINITY, "year"],
+  ];
+  let value = abs;
+  let label = "second";
+  let prev = 1;
+  for (const [limit, name] of units) {
+    if (abs < limit) {
+      value = Math.floor(abs / prev);
+      label = name;
+      break;
+    }
+    prev = limit;
+    label = name;
+  }
+  if (label === "second" && value < 45)
+    return future ? "in a moment" : "just now";
+  const plural = value === 1 ? label : `${label}s`;
+  return future ? `in ${value} ${plural}` : `${value} ${plural} ago`;
+}
+
+export function absoluteTime(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d+Z$/, "Z");
+}
+
+/**
+ * Middle truncation for file paths: the repo tells you where you are, the
+ * basename tells you what it is, and the middle is the part nobody reads.
+ * Returns the input untouched when it already fits.
+ */
+export function middleTruncate(value: string, max = 44): string {
+  if (value.length <= max) return value;
+  const keep = max - 1;
+  const head = Math.ceil(keep / 2);
+  const tail = Math.floor(keep / 2);
+  return `${value.slice(0, head)}…${value.slice(value.length - tail)}`;
+}
+
+/**
+ * The noun that goes with a count. A first catalog is full of ones - one
+ * context, one service, one aggregate - and "1 services" is the first thing
+ * that makes the page look generated rather than written.
+ */
+export function plural(n: number, one: string, many = `${one}s`): string {
+  return n === 1 ? one : many;
+}