@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/app/SidebarFooter.tsx

@@ -1,17 +1,17 @@
-import { useMemo } from "react";
 import { NavLink } from "react-router";
 import {
   Check,
   PanelLeftOpen,
+  Puzzle,
   Settings2,
   TriangleAlert,
 } from "lucide-react";
 
 import { allModules } from "../catalog";
+import { catalog } from "../data";
 import { KindIcon } from "../components/kind";
 import { CompassRose } from "../components/logo";
-import { catalog, index } from "../data";
-import { allProblems } from "../lib/all-problems";
+import { useProblems } from "../lib/use-problems";
 import type { Kind } from "../lib/kinds";
 import { paths } from "../routes";
 
@@ -28,7 +28,7 @@ export function SidebarBottomGroup() {
   // opens. The badge is red while anything on it is an error and amber when
   // only the schema disagrees with itself - a page of warnings is not a clean
   // estate, and a green tick over it would be the one lie the row can tell.
-  const found = useMemo(() => allProblems(catalog, index), []);
+  const found = useProblems();
   const errors = found.filter((p) => p.severity === "error").length;
   const colour =
     errors > 0 ? "var(--status-unresolved)" : "var(--status-declared)";
@@ -76,6 +76,22 @@ export function SidebarBottomGroup() {
           </span>
         )}
       </NavLink>
+      <NavLink
+        to={paths.plugins()}
+        data-nav-item
+        title="Plugins — what Portolan can read, and what it makes"
+        style={({ isActive }) => ({
+          paddingLeft: indent(0),
+          background: isActive ? "var(--surface-2)" : undefined,
+          borderLeftWidth: 2,
+          borderLeftStyle: "solid",
+          borderLeftColor: isActive ? "var(--accent)" : "transparent",
+        })}
+        className="tree-row flex items-center gap-1.5 py-[3px] pr-2 text-muted t-micro transition-colors hover:bg-surface hover:text-ink"
+      >
+        <Puzzle size={14} aria-hidden className="block shrink-0" />
+        <span className="truncate">Plugins</span>
+      </NavLink>
       <NavLink
         to={paths.settings()}
         data-nav-item

package/src/catalog-docs.test.ts

@@ -0,0 +1,64 @@
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { catalogDocs } from "./catalog-docs";
+// @ts-expect-error The build's documentation mount is a plain JavaScript module.
+import { siteDocs } from "../scripts/site-docs.mjs";
+
+const roots: string[] = [];
+afterEach(() => roots.splice(0).forEach((root) => rmSync(root, { recursive: true, force: true })));
+
+describe("catalog documentation URLs", () => {
+  it.each(["default", "avia", "portolan"])("opens the files actually published for root catalog %s", (id) => {
+    const root = mkdtempSync(join(tmpdir(), "catalog-docs-"));
+    roots.push(root);
+    const out = join(root, "generated", "markdown");
+    const dist = join(root, "dist");
+    mkdirSync(out, { recursive: true });
+    mkdirSync(dist);
+    writeFileSync(join(out, "llms.txt"), "# Catalog\n[Home](README.md)\n");
+    writeFileSync(join(out, "llms-full.txt"), "# Full catalog\n");
+    writeFileSync(join(out, "README.md"), "# Home\n");
+    const manifest = { generate: [{ plugin: "markdown", ...(id === "default" ? {} : { catalog: id }), out }] };
+    siteDocs({ manifest, dist });
+
+    const urls = catalogDocs(manifest, id, "/portolan/")!;
+    expect(urls.index).toBe("/portolan/llms.txt");
+    const published = (url: string) => readFileSync(join(dist, url.slice("/portolan/".length)), "utf8");
+    expect(published(urls.index)).toContain("[Home](docs/README.md)");
+    expect(published(urls.full)).toBe("# Full catalog\n");
+    expect(published(`${urls.pages}README.md`)).toBe("# Home\n");
+  });
+
+  it("uses a nested output directory even when it differs from the catalog id", () => {
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "avia", out: "./generated/docs/" },
+      { plugin: "markdown", catalog: "example", out: "generated/docs/samples" },
+    ] };
+    expect(catalogDocs(manifest, "example", "/portolan")).toEqual({
+      pages: "/portolan/docs/samples/",
+      index: "/portolan/docs/samples/llms.txt",
+      full: "/portolan/docs/samples/llms-full.txt",
+    });
+  });
+
+  it("preserves the demo's example paths and supports a site served at /", () => {
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "portolan", out: "docs" },
+      { plugin: "markdown", catalog: "example", out: "docs/example" },
+    ] };
+    expect(catalogDocs(manifest, "example", "/")?.index).toBe("/docs/example/llms.txt");
+    expect(catalogDocs(manifest, "portolan", "/")?.index).toBe("/llms.txt");
+  });
+
+  it("does not invent URLs for missing or unmounted documentation", () => {
+    expect(catalogDocs({}, "default", "/")).toBeNull();
+    const manifest = { generate: [
+      { plugin: "markdown", catalog: "avia", out: "docs" },
+      { plugin: "markdown", catalog: "example", out: "docs-other" },
+    ] };
+    expect(catalogDocs(manifest, "unknown", "/")).toBeNull();
+    expect(catalogDocs(manifest, "example", "/")).toBeNull();
+  });
+});

package/src/catalog-docs.ts

@@ -0,0 +1,35 @@
+export interface DocsManifest {
+  generate?: { plugin: string; catalog?: string; out: string }[];
+}
+
+export interface CatalogDocs {
+  pages: string;
+  index: string;
+  full: string;
+}
+
+/** Match site-docs.mjs: the first markdown output is mounted at docs/.
+ * Other catalogs are available when generated inside that output directory.
+ */
+export function catalogDocs(
+  manifest: DocsManifest,
+  profileId: string,
+  base: string,
+): CatalogDocs | null {
+  const steps = manifest.generate?.filter((step) => step.plugin === "markdown") ?? [];
+  const root = steps[0];
+  const selected = steps.find((step) => step.catalog === profileId)
+    ?? steps.find((step) => !step.catalog);
+  if (!root || !selected) return null;
+
+  const directory = (out: string) => new URL(`${out.replace(/\/$/, "")}/`, "https://workspace.invalid/").pathname;
+  const rootPath = directory(root.out);
+  const selectedPath = directory(selected.out);
+  if (!selectedPath.startsWith(rootPath)) return null;
+
+  const prefix = base.endsWith("/") ? base : `${base}/`;
+  const suffix = selectedPath.slice(rootPath.length);
+  const pages = `${prefix}docs/${suffix}`;
+  const indexRoot = suffix ? pages : prefix;
+  return { pages, index: `${indexRoot}llms.txt`, full: `${indexRoot}llms-full.txt` };
+}

package/src/catalog-error.test.ts

@@ -21,6 +21,21 @@ function failureOf(catalog: Catalog): CatalogError {
 }
 
 describe("CatalogError.path", () => {
+  it("allows rootless source groups while preserving aggregate root validation", () => {
+    const data = clone();
+    const aggregate = data.contexts[0]!.services[0]!.aggregates[0]!;
+    aggregate.root = "";
+    delete aggregate.lifecycle;
+    expect(() => validateCatalog(data)).toThrow(/names no root/);
+    aggregate.kind = "model-group";
+    expect(() => validateCatalog(data)).not.toThrow();
+    aggregate.root = aggregate.entities[0]!.name;
+    expect(() => validateCatalog(data)).toThrow(/cannot declare an aggregate root/);
+    aggregate.root = "";
+    aggregate.lifecycle = { states: ["Active"], transitions: [] };
+    expect(() => validateCatalog(data)).toThrow(/cannot declare an aggregate root or lifecycle/);
+  });
+
   it("names the flow and the step for a step that points at a missing lane", () => {
     const bad = clone();
     const flow = bad.flows[0];

package/src/catalog-index.ts

@@ -6,6 +6,7 @@ import type {
   BoundedContext,
   Catalog,
   Column,
+  Deployment,
   Enum,
   Event,
   External,
@@ -21,12 +22,14 @@ import type {
   View,
 } from "./catalog-model.ts";
 import {
+  allDeployments,
   allExternals,
   allModules,
   allStores,
   allTerms,
   aggregateBlocks,
   columnId,
+  deploys,
   enumsOf,
   storeViews,
   viewReads,
@@ -140,6 +143,14 @@ export interface CatalogIndex {
   lineageInto: Map<string, string[]>;
   /** service id -> stores it owns, in catalog order */
   storesOwnedBy: Map<string, Store[]>;
+  /**
+   * service id -> where it runs, in snapshot order.
+   *
+   * Joined here rather than written by the fetcher, which reads a control
+   * plane and knows no service: an Application is this service's when it
+   * deploys from the service's repository, inside the service's directory.
+   */
+  deploymentsByService: Map<string, Deployment[]>;
   /** aggregate id -> tables naming it in `persists`, in catalog order */
   tablesByAggregate: Map<string, Table[]>;
   /** aggregate id -> views naming it in `persists`, in catalog order */
@@ -323,6 +334,19 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     }
   }
 
+  // Deployments come after the services because the join runs over them: a
+  // row is placed on every service whose repository and directory it deploys
+  // from, and on none when nobody in the estate claims that repository.
+  const deploymentsByService = new Map<string, Deployment[]>();
+  for (const deployment of allDeployments(catalog)) {
+    for (const service of serviceById.values()) {
+      if (!deploys(deployment, service)) continue;
+      const placed = deploymentsByService.get(service.id) ?? [];
+      placed.push(deployment);
+      deploymentsByService.set(service.id, placed);
+    }
+  }
+
   // Stores come after the domain tree because they point into it: a table says
   // which aggregate it persists, and a column which block it maps to, so both
   // are resolved against maps that are already full.
@@ -467,6 +491,7 @@ export function buildIndex(catalog: Catalog): CatalogIndex {
     lineageFrom,
     lineageInto,
     storesOwnedBy,
+    deploymentsByService,
     moduleById,
     moduleBySlug,
     interfacesByModule,

package/src/catalog-model.ts

@@ -44,6 +44,13 @@ export interface Catalog {
    * to pin and renders as it did before there was anything to pin.
    */
   repos?: RepoPin[];
+  /**
+   * Where the estate's services run, read from what deploys them. Optional
+   * in the file and never optional downstream, exactly like `repos`: an
+   * estate nobody has pointed at a deployer renders as it did before there
+   * was anything to place.
+   */
+  deployments?: Deployment[];
   /**
    * The systems outside the estate that a service calls on a contract: a
    * payment provider, a tax API, a carrier. Nobody here builds one, so it has
@@ -173,6 +180,24 @@ export interface Service {
    * same as a service that cannot be built.
    */
   commands?: Command[];
+  /**
+   * The names this service answers on, read from what deploys it: a
+   * Kubernetes Service's name in its short, namespaced, `svc` and fully
+   * qualified forms, and the hosts of the Ingress or HTTPRoute in front of
+   * it. Written so that a call another service is configured to make to
+   * `pricing.shop.svc` can find the service that answers. Absent when
+   * nothing in the tree says where the service is reachable.
+   */
+  hosts?: string[];
+  /**
+   * The in-cluster names this service's workload is configured to reach,
+   * read out of its environment and config maps and reduced to the host
+   * alone. A value is never kept: not the variable it came from, not the
+   * scheme, port, path or credentials around the name. Only a name the
+   * cluster resolves qualifies, so a password in an environment variable is
+   * not something this list can hold by shape.
+   */
+  dials?: string[];
 }
 
 /**
@@ -297,7 +322,11 @@ export interface RpcMethod {
 }
 
 export interface HttpRoute {
-  /** Upper case: `POST`. */
+  /**
+   * Upper case: `POST`. Empty when a framework extractor proved the mount but
+   * no declaration proved the verb; such a route is never matched against an
+   * outbound call, and renderers show the path alone.
+   */
   method: string;
   /** As templated in the document: `/v1/users/{id}`. */
   path: string;
@@ -361,7 +390,32 @@ export interface EdgeVia {
   flow: string; // Flow.slug
   step: string; // Step.id
 }
+/** Source facts remain separate from the merge's choice of provider. */
+export interface HTTPDestination {
+  callSite: string;
+  endpointExpression: string;
+  method: string;
+  localPath?: string;
+  baseURL?: HTTPBaseURL;
+  serviceDiscoveryAlias?: string;
+  fullPath?: string;
+  join?: { expression: string; source: string };
+  /** Runtime URL modifiers after the proven join; not evaluated statically. */
+  transforms?: { expression: string; source: string }[];
+  resolution?: { basis: "full-path" | "exact-route" | "unique-suffix" | "kubernetes-host"; provider: string; route: string };
+}
+export interface HTTPBaseURL {
+  expression: string;
+  configField?: string;
+  environmentVariable?: string;
+  value?: string;
+  kind: "literal" | "config-default" | "symbolic";
+  source: string;
+  optionSource?: string;
+}
 export interface RpcCall {
+  evidence?: RelationEvidence[];
+  destination?: HTTPDestination;
   id: string; // "<proto.package.Service>/<Method>"
   peer: string; // service id if resolved, else raw name
   status: Status;
@@ -442,12 +496,112 @@ export interface RepoPin {
   /** The commit the copy was made of. Full sha: it is not resolved locally, so there is nothing to expand it against. */
   commit: string;
 }
+
+/**
+ * One place a service runs: an Argo CD Application, as the deployer listed
+ * it, reduced to what a deploy changes.
+ *
+ * A list on the catalog rather than a field on `Service`, for two reasons.
+ * The fetcher that writes it reads a control plane, not a service's tree, so
+ * it does not know which service an Application is; the join is made where
+ * the whole estate is known, by the repository and path the Application
+ * deploys from against the ones a service says it lives at. And one service
+ * stands in several places - staging, production, a second region - and
+ * each is its own row.
+ *
+ * Nothing here moves without a deploy. Health, sync state and the time of
+ * the last operation move on their own, and a page regenerated from the
+ * tree cannot follow them; they are not kept.
+ */
+export interface Deployment {
+  /** `<argocd namespace>/<application name>`: unique per control plane. */
+  id: string;
+  /** The Application's name, as `argocd app get` takes it. */
+  name: string;
+  /** The Argo CD project it belongs to. */
+  project: string;
+  /**
+   * Where a reader would say it runs: the application's environment label,
+   * else the cluster it deploys to. What the page groups by.
+   */
+  environment: string;
+  /** The destination cluster, by its Argo CD name; `in-cluster` for the one Argo CD runs in. */
+  cluster: string;
+  /** The destination namespace. */
+  namespace: string;
+  /** The repository it deploys from, spelled the way `Service.repo` spells it. Empty for a chart from a registry. */
+  repo: string;
+  /** The directory in that repository the manifests are read from, as a reader would type it. Empty for a chart. */
+  path: string;
+  /** The Helm chart name, when the source is a chart registry rather than a repository. */
+  chart?: string;
+  /** What the Application tracks: a branch, a tag, a chart version. */
+  targetRevision: string;
+  /** What is deployed now: the commit, or chart version, the last sync resolved `targetRevision` to. */
+  revision: string;
+  /** `helm`, `kustomize`, `directory` or `plugin`, as Argo CD says it; empty until it has said. */
+  tool: string;
+  /** The Application in the Argo CD UI. */
+  url: string;
+  /**
+   * The service it deploys, by id, when the Application's labels say so:
+   * `app.kubernetes.io/part-of` and `app.kubernetes.io/name`, the same
+   * labels a workload carries. A GitOps repository's Application points at
+   * an overlay, not at the service's directory, so the path alone cannot
+   * place it; the labels can, and an ApplicationSet stamps them on every
+   * Application it makes. Absent when the labels are, and the path decides.
+   */
+  service?: string;
+  /** The container images the deployed resources run, as the deployer summarised them, sorted. */
+  images?: string[];
+  /**
+   * Who said so. `manifest` is a row an extractor read out of a GitOps
+   * tree: what should run. `api` is a row a fetcher read off the deployer:
+   * what does. `both` is one the merge folded from the two, which is the
+   * ordinary case for an estate that keeps both, and the only one that can
+   * carry drift. Absent reads as `api`, which is what every row was before
+   * there were trees to read.
+   */
+  basis?: DeploymentBasis;
+  /**
+   * What the tree says where it and the deployer disagree, set by the merge
+   * when both spoke (portolan.0013). A field is present only when the two
+   * differ; a row with no drift has no field at all.
+   */
+  drift?: DeploymentDrift;
+}
+
+export type DeploymentBasis = "manifest" | "api" | "both";
+
+export const DEPLOYMENT_BASES: readonly DeploymentBasis[] = [
+  "manifest",
+  "api",
+  "both",
+] as const;
+
+/** The GitOps tree's word on the fields where the deployer says otherwise. */
+export interface DeploymentDrift {
+  project?: string;
+  cluster?: string;
+  namespace?: string;
+  path?: string;
+  targetRevision?: string;
+  /** The images the overlay pins, when they are not the ones running. */
+  images?: string[];
+}
+
+/** The basis a row carries, `api` when it carries none. */
+export function deploymentBasis(deployment: Deployment): DeploymentBasis {
+  return deployment.basis ?? "api";
+}
 export interface Aggregate {
   id: string;
   slug: string;
   name: string;
   readme: string;
-  /** Name of the entity that is the aggregate root; must be one of `entities`. */
+  /** A source grouping has no confirmed aggregate boundary. Omitted for aggregates. */
+  kind?: "model-group";
+  /** Name of the root entity; empty only for a model-group. */
   root: string;
   entities: Entity[];
   valueObjects: ValueObject[];
@@ -506,6 +660,15 @@ export interface Operation {
    * estate can only reach from inside, which is sometimes exactly the point.
    */
   exposedBy?: string[];
+  /**
+   * What the caller hands in: the command's or query's own shape, as the
+   * message class declares it - the fields of `CreateCourseCommand`. Absent
+   * when the extractor does not read messages; empty is a message that
+   * carries nothing, `FindCoursesCounterQuery`.
+   */
+  fields?: Field[];
+  /** Where the handler is, `path:line`, for the reader who wants the code. */
+  source?: string;
 }
 
 /**
@@ -656,7 +819,31 @@ export interface Field {
   ref?: string;
   /** Protobuf field number; absent for sources whose wire has no field numbers. */
   number?: number;
+  /**
+   * The source says the field must be sent: a Protovalidate `required`, a
+   * name in a JSON Schema `required` list. Absent means the source does not
+   * say, which in proto3 and OpenAPI alike means it may be left out.
+   */
+  required?: boolean;
+  /** What the source says a value must satisfy, in the order it said it. */
+  rules?: FieldRule[];
 } // ref -> defs key
+/**
+ * One constraint on a field's value, in the catalog's own vocabulary so a
+ * Protovalidate `min_len` and a JSON Schema `minLength` are one rule:
+ * `min_len`, `max_len`, `len`, `pattern`, `prefix`, `suffix`, `contains`,
+ * `not_contains`, `format`, `gt`, `gte`, `lt`, `lte`, `const`, `in`,
+ * `not_in`, `multiple_of`, `min_items`, `max_items`, `unique`, `min_pairs`,
+ * `max_pairs`, `defined_only`, `lt_now`, `gt_now`, `cel`. A rule on what a
+ * list holds is prefixed `items.`; on a map's keys or values, `keys.` or
+ * `values.`. A custom option the catalog has no word for keeps the name the
+ * source gave it, `(acme.pii)`, so it is shown rather than lost.
+ */
+export interface FieldRule {
+  name: string;
+  /** The bound as the source wrote it, text so a 64-bit number survives; absent for a bare flag such as `unique`. */
+  value?: string;
+}
 export interface TypeDef {
   fields: Field[];
 }
@@ -679,6 +866,7 @@ export type StoreKind =
   | "mongodb"
   | "clickhouse"
   | "s3"
+  | "dynamodb"
   | "other";
 
 export const STORE_KINDS: readonly StoreKind[] = [
@@ -689,6 +877,7 @@ export const STORE_KINDS: readonly StoreKind[] = [
   "mongodb",
   "clickhouse",
   "s3",
+  "dynamodb",
   "other",
 ] as const;
 
@@ -734,7 +923,7 @@ export interface RedisKeyspace {
   value?: string;
   source?: string;
   /** Aggregate or block whose value this key family holds, when provable. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   /** Individual client calls, before they are folded into `operations`. */
   accesses?: RedisAccess[];
 }
@@ -767,13 +956,14 @@ export const TABLE_ROLES: readonly TableRole[] = [
 ] as const;
 
 export interface Table {
+  evidence?: RelationEvidence[];
   id: string; // "<store id>.<table>"
   name: string;
   doc?: string;
   columns: Column[];
   indexes?: TableIndex[];
   /** The domain object this table holds: an aggregate id, and optionally a block id. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   role?: TableRole;
   /** Source-backed repository methods that read or write this table. */
   accesses?: TableAccess[];
@@ -853,7 +1043,7 @@ export interface View {
   /** The SELECT, as the migration declares it. Shown, never parsed. */
   definition?: string;
   /** The domain object this view presents, when it presents exactly one. */
-  persists?: { aggregate?: string; block?: string };
+  persists?: { aggregate?: string; block?: string; evidence?: RelationEvidence[] };
   /** Migration or model file, as a reader would open it. */
   source?: string;
 }
@@ -886,6 +1076,47 @@ export interface Flow {
   owner: string;
   participants: Participant[]; // order is significant - it is the lane order
   steps: FlowNode[];
+  /**
+   * Recordings of this flow running: one per trace a verifier kept, each
+   * naming the steps it showed with what the spans said about them. Examples
+   * of data, not evidence - the evidence is the status on the step.
+   */
+  examples?: FlowExample[];
+}
+/** One recorded run of a flow, read from one trace. */
+export interface FlowExample {
+  /** "<recording>#<trace id>": unique within the flow, stable across runs. */
+  id: string;
+  /**
+   * The file the trace was read from, relative to the verify step's input
+   * root - where an uploaded recording is kept.
+   */
+  recording: string;
+  traceId: string;
+  /** When the root span started, RFC 3339 UTC; absent when the recording has no clock. */
+  recordedAt?: string;
+  /** Root start to the last end the trace shows. */
+  durationMs: number;
+  /** The steps this trace showed, in the order it showed them. */
+  steps: ExampleStep[];
+}
+/**
+ * What one span said about one step. Only an allowlist of attributes is
+ * carried: names, verbs, routes, status codes - never a query text, a header
+ * or a path with an id in it.
+ */
+export interface ExampleStep {
+  step: string;
+  label?: string;
+  durationMs: number;
+  attributes?: Record<string, string>;
+}
+/**
+ * How many recordings showed a step. On a declared step it accompanies the
+ * raised status; on a step no source declares it is why the step is there.
+ */
+export interface StepSeen {
+  traces: number;
 }
 export interface FlowTrigger {
   kind:
@@ -908,7 +1139,18 @@ export interface Participant {
   label?: string;
 }
 export type FlowNode = Step | Parallel | Alt | Loop;
+/** Source facts used to derive a relationship; not a runtime trace. */
+export interface RelationEvidence {
+  kind: "call-site" | "function" | "binding" | "contract" | "resolution" | "unresolved";
+  rule: string;
+  source?: string;
+  symbol?: string;
+  candidates?: string[];
+}
+
 export interface Step {
+  evidence?: RelationEvidence[];
+  destination?: HTTPDestination;
   type: "step";
   id: string;
   from: string;
@@ -931,6 +1173,8 @@ export interface Step {
   handoff?: FlowHandoff;
   /** Repository call resolved to a concrete store operation after merge. */
   storeAccess?: FlowStoreAccess;
+  /** Recordings that showed this hop; set by a verifier. */
+  seen?: StepSeen;
 }
 export interface HTTPResponse {
   status?: number;
@@ -986,6 +1230,12 @@ export interface AltBranch {
   steps: FlowNode[];
   /** True when the flow stops here instead of continuing past the alt. */
   terminal?: boolean;
+  /**
+   * Recordings that went this way, on a frame a verifier wrote where the
+   * recordings parted. A branch with no steps and a count is the recordings
+   * that went no further.
+   */
+  seen?: StepSeen;
 }
 export interface Loop {
   type: "loop";
@@ -1229,6 +1479,44 @@ export function allRepos(catalog: Catalog): RepoPin[] {
   return catalog.repos ?? [];
 }
 
+/** Every place a service runs. Absent means none, exactly as with repos. */
+export function allDeployments(catalog: Catalog): Deployment[] {
+  return catalog.deployments ?? [];
+}
+
+/**
+ * Whether a deployment is of this service. The labels decide when the
+ * Application carries them: `service` is the id, and an Application
+ * labelled for one service is not another's however its path reads. Without
+ * labels, the path: the same repository, and the manifests read from inside
+ * the service's directory - or from anywhere in the repository when the
+ * service is the whole of it. An Application that matches nothing is a fact
+ * for the Problems page rather than for a guess.
+ */
+export function deploys(deployment: Deployment, service: Service): boolean {
+  if (deployment.service) return deployment.service === service.id;
+  if (!deployment.repo || deployment.repo !== service.repo) return false;
+  const root = service.path.replace(/^\/+|\/+$/g, "");
+  if (!root) return true;
+  return deployment.path === root || deployment.path.startsWith(`${root}/`);
+}
+
+/**
+ * The environment a reader would say a deployment stands in: the one the
+ * deployer named, else the cluster, else the one word that says neither was
+ * said. Every picture and filter groups by this, so it is decided once.
+ */
+export function environmentOf(deployment: Deployment): string {
+  return deployment.environment || deployment.cluster || "unplaced";
+}
+
+/** Where this service runs, in catalog order: the snapshot's, which is by id. */
+export function deploymentsOf(catalog: Catalog, service: Service): Deployment[] {
+  return allDeployments(catalog).filter((deployment) =>
+    deploys(deployment, service),
+  );
+}
+
 /** Who to ask about a service, without the caller having to know the field is optional. */
 export function ownersOf(service: Service): string[] {
   return service.owners ?? [];