@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/lib/rule-entries.ts

@@ -0,0 +1,39 @@
+// What a switch or a re-grade does to the manifest's entries.
+//
+// The Rules page and the Problems page both flip a rule; the entry they
+// write is one shape, kept here so the two cannot write it differently.
+
+import type { ProblemRule, ProblemRuleEntry, RuleSeverity } from "./problem-rules";
+
+/** The entries with one rule switched. A shipped rule back on with nothing else to say loses its entry. */
+export function switched(entries: ProblemRuleEntry[], rule: ProblemRule, enabled: boolean, reason: string): ProblemRuleEntry[] {
+  const existing = entries.find((entry) => entry.id === rule.id);
+  if (rule.builtin) {
+    const next: ProblemRuleEntry = { id: rule.id };
+    if (!enabled) next.enabled = false;
+    if (existing?.severity) next.severity = existing.severity;
+    const why = enabled ? existing?.reason : reason || existing?.reason;
+    if (why && (!enabled || next.severity)) next.reason = why;
+    if (enabled && !next.severity) return entries.filter((entry) => entry.id !== rule.id);
+    return existing ? entries.map((entry) => (entry.id === rule.id ? next : entry)) : [...entries, next];
+  }
+  return entries.map((entry) => {
+    if (entry.id !== rule.id) return entry;
+    const { enabled: _enabled, ...rest } = entry;
+    return enabled ? rest : { ...rest, enabled: false, ...(reason ? { reason } : {}) };
+  });
+}
+
+/** The entries with one rule's severity set; a shipped rule back at its own severity loses the field. */
+export function regraded(entries: ProblemRuleEntry[], rule: ProblemRule, severity: RuleSeverity): ProblemRuleEntry[] {
+  const existing = entries.find((entry) => entry.id === rule.id);
+  if (rule.builtin) {
+    const next: ProblemRuleEntry = { id: rule.id };
+    if (existing?.enabled === false) next.enabled = false;
+    if (severity !== rule.defaultSeverity) next.severity = severity;
+    if (existing?.reason) next.reason = existing.reason;
+    if (next.enabled === undefined && !next.severity) return entries.filter((entry) => entry.id !== rule.id);
+    return existing ? entries.map((entry) => (entry.id === rule.id ? next : entry)) : [...entries, next];
+  }
+  return entries.map((entry) => (entry.id === rule.id ? { ...entry, severity } : entry));
+}

package/src/lib/{data-problems.test.ts → rules-data.test.ts}

@@ -6,36 +6,38 @@ import { rawCatalog } from "../test-catalog";
 import { buildIndex, validateCatalog } from "../catalog";
 import type { Catalog } from "../catalog";
 import type { Problem } from "./derive";
-import { dataProblems } from "./data-problems";
+import { builtinProblems } from "./problem-rules";
+
+const DATA = ["cross-service-fk", "cross-service-lineage", "cross-service-view", "shared-store", "persistence-drift", "column-type", "outbox-payload"];
 
 const clone = (): Catalog =>
   JSON.parse(JSON.stringify(rawCatalog)) as unknown as Catalog;
 
 function found(catalog: Catalog) {
-  return dataProblems(catalog, buildIndex(validateCatalog(catalog)));
+  return builtinProblems(catalog, buildIndex(validateCatalog(catalog)), DATA);
 }
 
-const kinds = (list: { kind: string }[]) => list.map((p) => p.kind);
+const kinds = (list: { rule: string }[]) => list.map((p) => p.rule);
 
 describe("the sample estate", () => {
   const problems = found(clone());
 
   it("reports the intentional cross-service foreign key", () => {
-    const fk = problems.find((p) => p.kind === "cross-service-fk");
+    const fk = problems.find((p) => p.rule === "cross-service-fk");
     expect(fk?.id).toBe("delivery.core.pg.packages.order_id");
     expect(fk?.peer).toBe("shop.oms.pg.orders");
     expect(fk?.severity).toBe("error");
   });
 
   it("reports the table one service writes in another's database", () => {
-    const shared = problems.find((p) => p.kind === "shared-store");
+    const shared = problems.find((p) => p.rule === "shared-store");
     expect(shared?.id).toBe("shop.oms.pg.price_snapshots");
     expect(shared?.peer).toBe("shop.pricing");
     expect(shared?.severity).toBe("error");
   });
 
   it("reports no persistence drift: every table's columns follow its aggregate", () => {
-    expect(problems.filter((p) => p.kind === "persistence-drift")).toEqual([]);
+    expect(problems.filter((p) => p.rule === "persistence-drift")).toEqual([]);
   });
 
   it("reports a renamed table whose columns did not follow", () => {
@@ -45,13 +47,13 @@ describe("the sample estate", () => {
       ?.tables.find((t) => t.name === "orders");
     if (!orders) throw new Error("fixture has no orders table");
     for (const column of orders.columns) if (column.maps) column.maps = `Order.${column.name}Gone`;
-    const drift = found(drifted).find((p) => p.kind === "persistence-drift");
+    const drift = found(drifted).find((p) => p.rule === "persistence-drift");
     expect(drift?.id).toBe("shop.oms.pg.orders");
     expect(drift?.severity).toBe("warning");
   });
 
   it("reports every type disagreement and nothing else", () => {
-    const types = problems.filter((p) => p.kind === "column-type");
+    const types = problems.filter((p) => p.rule === "column-type");
     expect(types.map((p) => p.id)).toEqual([
       "shop.oms.pg.orders.id",
       "shop.oms.pg.order_items.quantity",
@@ -64,7 +66,7 @@ describe("the sample estate", () => {
   });
 
   it("reports the value delivery copies out of the OMS schema", () => {
-    const copied = problems.filter((p) => p.kind === "cross-service-lineage");
+    const copied = problems.filter((p) => p.rule === "cross-service-lineage");
     expect(copied.map((p) => p.id)).toEqual([
       "delivery.core.pg.packages.ship_to",
     ]);
@@ -78,7 +80,7 @@ describe("the sample estate", () => {
   it("says nothing about lineage that stays inside one service", () => {
     const inside = problems.filter(
       (p) =>
-        p.kind === "cross-service-lineage" &&
+        p.rule === "cross-service-lineage" &&
         p.id.startsWith("shop.oms.pg.outbox"),
     );
     expect(inside).toEqual([]);
@@ -104,7 +106,7 @@ describe("cases that only look like problems", () => {
     const problems = found(clone());
     const inside = problems.filter(
       (p) =>
-        p.kind === "cross-service-fk" &&
+        p.rule === "cross-service-fk" &&
         p.id.startsWith("shop.oms.pg.order_items"),
     );
     expect(inside).toEqual([]);
@@ -120,7 +122,7 @@ describe("cases that only look like problems", () => {
     stops.persists = { aggregate: "shop.oms.order" };
 
     const shared = found(catalog).filter(
-      (p) => p.kind === "shared-store" && p.id === stops.id,
+      (p) => p.rule === "shared-store" && p.id === stops.id,
     );
     expect(shared).toEqual([]);
   });
@@ -129,7 +131,7 @@ describe("cases that only look like problems", () => {
     const problems = found(clone());
     const derived = problems.filter(
       (p) =>
-        p.kind === "persistence-drift" &&
+        p.rule === "persistence-drift" &&
         p.id === "delivery.core.pg.route_stops",
     );
     expect(derived).toEqual([]);
@@ -139,7 +141,7 @@ describe("cases that only look like problems", () => {
     const problems = found(clone());
     expect(
       problems.filter(
-        (p) => p.kind === "persistence-drift" && p.id === "shop.oms.pg.orders",
+        (p) => p.rule === "persistence-drift" && p.id === "shop.oms.pg.orders",
       ),
     ).toEqual([]);
   });
@@ -154,7 +156,7 @@ describe("an outbox with nothing in it", () => {
     if (!outbox) throw new Error("fixture has no outbox");
     outbox.columns = outbox.columns.filter((c) => c.type !== "jsonb");
 
-    const problem = found(catalog).find((p) => p.kind === "outbox-payload");
+    const problem = found(catalog).find((p) => p.rule === "outbox-payload");
     expect(problem?.severity).toBe("warning");
     expect(problem?.id).toBe("shop.oms.pg.outbox");
     expect(problem?.peer).toBe("shop.oms.pg");
@@ -174,5 +176,5 @@ describe("a catalog with no stores", () => {
 
 // A compile-time check that the shared shape really is shared: the page renders
 // one row component over both lists, so the two must stay one type.
-const _shape: (p: Problem) => string = (p) => `${p.severity}:${p.kind}`;
+const _shape: (p: Problem) => string = (p) => `${p.severity}:${p.rule}`;
 void _shape;

package/src/lib/rules-deploy.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import { buildIndex } from "../catalog";
+import type { Catalog, Deployment } from "../catalog";
+import { builtinProblems } from "./problem-rules";
+
+const deployProblems = (catalog: Catalog) => builtinProblems(catalog, buildIndex(catalog), ["deployment-unclaimed", "deployment-drift"]);
+
+const service = (id: string, path: string) => ({
+  id,
+  slug: id.split(".")[1] ?? id,
+  name: id,
+  repo: "github.com/acme/shop",
+  path,
+  readme: "",
+  provides: [],
+  consumes: [],
+  aggregates: [],
+});
+
+const placed = (
+  name: string,
+  repo: string,
+  path: string,
+  extra: Partial<Deployment> = {},
+): Deployment => ({
+  id: `argocd/${name}`,
+  name,
+  project: "shop",
+  environment: "prod",
+  cluster: "in-cluster",
+  namespace: "shop",
+  repo,
+  path,
+  targetRevision: "main",
+  revision: "a".repeat(40),
+  tool: "kustomize",
+  url: `https://argocd.example.com/applications/argocd/${name}`,
+  ...extra,
+});
+
+const estate = (deployments: Deployment[]): Catalog => ({
+  generatedAt: "",
+  commit: "",
+  contexts: [
+    {
+      id: "shop",
+      slug: "shop",
+      name: "Shop",
+      summary: "",
+      services: [service("shop.cart", "services/cart"), service("shop.oms", "")],
+    },
+  ],
+  defs: {},
+  flows: [],
+  adrs: [],
+  deployments,
+});
+
+describe("deployments the catalog cannot place", () => {
+  it("is quiet when every Application deploys from a directory a service lives at", () => {
+    const catalog = estate([
+      placed("cart", "github.com/acme/shop", "services/cart/deploy"),
+      // A service whose path is the whole repository claims any directory of it.
+      placed("oms", "github.com/acme/shop", "anything/at/all"),
+    ]);
+    expect(deployProblems(catalog)).toEqual([]);
+  });
+
+  it("names the Application and where it deploys from, as a warning with no context", () => {
+    const catalog = estate([
+      placed("grafana", "github.com/acme/platform", "charts/grafana", {
+        namespace: "monitoring",
+      }),
+    ]);
+    const [problem, ...rest] = deployProblems(catalog);
+    expect(rest).toEqual([]);
+    expect(problem).toMatchObject({
+      rule: "deployment-unclaimed",
+      severity: "warning",
+      context: "",
+      service: "",
+      id: "argocd/grafana",
+      peer: "github.com/acme/platform/charts/grafana",
+    });
+    expect(problem?.note).toContain("grafana runs in prod, namespace monitoring");
+    expect(problem?.note).toContain("https://argocd.example.com/applications/argocd/grafana");
+  });
+
+  it("places by the labels when the Application carries them, and says so when they name nobody", () => {
+    const placedByLabel = estate([
+      placed("cart-prod", "github.com/acme/other", "envs/prod/shop/cart", { service: "shop.cart" }),
+    ]);
+    expect(deployProblems(placedByLabel)).toEqual([]);
+
+    const nobody = estate([
+      placed("grafana", "github.com/acme/platform", "charts/grafana", { service: "platform.grafana" }),
+    ]);
+    expect(deployProblems(nobody)[0]?.note).toContain("its labels name platform.grafana, which is no service of the estate");
+  });
+
+  it("reports drift on the service's row, in words, and stays quiet when the tree and the deployer agree", () => {
+    const agreed = estate([placed("cart-prod", "github.com/acme/shop", "services/cart/deploy", { basis: "both" })]);
+    expect(deployProblems(agreed)).toEqual([]);
+
+    const drifted = estate([
+      placed("cart-prod", "github.com/acme/shop", "services/cart/deploy", {
+        basis: "both",
+        images: ["ghcr.io/acme/cart:2.0.9"],
+        drift: { targetRevision: "release-2.1", images: ["ghcr.io/acme/cart:2.1.0"] },
+      }),
+    ]);
+    const [problem, ...rest] = deployProblems(drifted);
+    expect(rest).toEqual([]);
+    expect(problem).toMatchObject({ rule: "deployment-drift", severity: "warning", context: "shop", service: "shop.cart", id: "argocd/cart-prod", peer: "prod" });
+    expect(problem?.note).toBe(
+      "tracks release-2.1 in the tree, main deployed; pins ghcr.io/acme/cart:2.1.0 in the tree; running ghcr.io/acme/cart:2.0.9. https://argocd.example.com/applications/argocd/cart-prod",
+    );
+  });
+
+  it("says the chart when the Application deploys one from a registry", () => {
+    const catalog = estate([
+      placed("redis", "charts.bitnami.com/bitnami", "", { chart: "redis" }),
+    ]);
+    expect(deployProblems(catalog)[0]?.peer).toBe("chart redis");
+  });
+
+  it("does not place a deployment on a service in another repository at the same path", () => {
+    const catalog = estate([
+      placed("cart", "github.com/acme/other", "services/cart/deploy"),
+    ]);
+    expect(deployProblems(catalog)).toHaveLength(1);
+  });
+});

package/src/lib/{problems.test.ts → rules-edges.test.ts}

@@ -1,8 +1,13 @@
 import { describe, expect, it } from "vitest";
-import { catalog } from "../data";
-import { contextStats, edgeCount, problems } from "./derive";
+import { catalog, index } from "../data";
+import { contextStats, edgeCount } from "./derive";
+import { builtinProblems } from "./problem-rules";
+
+import { buildIndex } from "../catalog";
 import type { Catalog } from "../catalog";
 
+const problems = (of: Catalog) => builtinProblems(of, of === catalog ? index : buildIndex(of), ["rpc", "consumer"]);
+
 describe("problems", () => {
   it("finds every unresolved edge and nothing else", () => {
     for (const problem of problems(catalog)) {
@@ -13,7 +18,7 @@ describe("problems", () => {
         `${problem.id} names a service not in the catalog`,
       ).toBeDefined();
 
-      if (problem.kind === "rpc") {
+      if (problem.rule === "rpc") {
         const call = service?.consumes.find((c) => c.id === problem.id);
         expect(call?.status).toBe("unresolved");
         expect(call?.peer).toBe(problem.peer);

package/src/lib/{proto-problems.test.ts → rules-proto.test.ts}

@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vitest";
-import type { Catalog, CatalogIndex, Service } from "../catalog";
-import { protoProblems } from "./proto-problems";
+import { buildIndex } from "../catalog";
+import type { Catalog, Service } from "../catalog";
+import { builtinProblems } from "./problem-rules";
+
+const PROTO = ["proto-missing", "proto-drift"];
 
 function service(id: string, overrides: Partial<Service> = {}): Service {
   const slug = id.slice(id.indexOf(".") + 1);
@@ -141,36 +144,17 @@ const copiedPricing = (overrides = {}) =>
   });
 
 function found(catalog: Catalog) {
-  const serviceById = new Map<string, Service>();
-  const serviceContext = new Map<string, Catalog["contexts"][number]>();
-  const rpcProviderByMethod = new Map<string, Service>();
-  for (const context of catalog.contexts) {
-    for (const item of context.services) {
-      serviceById.set(item.id, item);
-      serviceContext.set(item.id, context);
-      for (const provided of item.provides) {
-        for (const method of provided.methods) {
-          rpcProviderByMethod.set(`${provided.id}/${method.name}`, item);
-        }
-      }
-    }
-  }
-  const index = {
-    serviceById,
-    serviceContext,
-    rpcProviderByMethod,
-  } as CatalogIndex;
-  return protoProblems(catalog, index);
+  return builtinProblems(catalog, buildIndex(catalog), PROTO);
 }
 
-describe("protoProblems", () => {
+describe("the proto rules", () => {
   it("reports a call whose provider answers on no such method", () => {
     const problems = found(
       catalogWith([pricing(), calling("pricing.v1.Pricing/ListPriceLists")]),
     );
 
     expect(problems).toHaveLength(1);
-    expect(problems[0]?.kind).toBe("proto-missing");
+    expect(problems[0]?.rule).toBe("proto-missing");
     expect(problems[0]?.severity).toBe("error");
     // The near end is the CALLER: that is the copy to go and look at.
     expect(problems[0]?.service).toBe("shop.oms");
@@ -238,7 +222,7 @@ describe("protoProblems", () => {
 
     expect(problems).toHaveLength(1);
     expect(problems[0]).toMatchObject({
-      kind: "proto-drift",
+      rule: "proto-drift",
       severity: "warning",
       service: "shop.oms",
       id: "pricing.v1.Pricing",

package/src/lib/{wire-problems.test.ts → rules-wire.test.ts}

@@ -9,7 +9,9 @@ import {
   type Service,
 } from "../catalog";
 import { catalog as estate } from "../data";
-import { wireProblems } from "./wire-problems";
+import { builtinProblems } from "./problem-rules";
+
+const WIRE = ["shared-channel", "channel-undeclared", "channel-unpublished", "message-encoding", "subscription-unresolved"];
 
 function event(id: string, channel?: string): Event {
   const name = id.slice(id.lastIndexOf(".") + 1);
@@ -84,7 +86,7 @@ function catalogWith(services: Service[]): Catalog {
 }
 
 function found(catalog: Catalog) {
-  return wireProblems(catalog, buildIndex(catalog));
+  return builtinProblems(catalog, buildIndex(catalog), WIRE);
 }
 
 const cart = () =>
@@ -95,7 +97,7 @@ const cart = () =>
     ]),
   ]);
 
-describe("wireProblems", () => {
+describe("the wire rules", () => {
   it("reports each side of a channel two services publish on", () => {
     const oms = service("shop.oms", [
       aggregate("shop.oms.order", [
@@ -109,7 +111,7 @@ describe("wireProblems", () => {
       ["shop.oms", "shop.oms.order.OrderPlaced", "shop.cart"],
     ]);
     const [first] = problems;
-    expect(first?.kind).toBe("shared-channel");
+    expect(first?.rule).toBe("shared-channel");
     expect(first?.severity).toBe("error");
     expect(first?.note).toContain("OrderPlaced");
     expect(first?.source).toBe("BasketCreated.ts");
@@ -150,7 +152,7 @@ describe("wireProblems", () => {
     );
     const problems = found(catalogWith([cart(), oms]));
 
-    expect(problems.filter((p) => p.kind === "shared-channel")).toHaveLength(2);
+    expect(problems.filter((p) => p.rule === "shared-channel")).toHaveLength(2);
     const theirs = problems.find((p) => p.service === "shop.oms");
     // No event of theirs to point at, so the row leads to the service.
     expect(theirs?.id).toBe("shop.oms");
@@ -166,7 +168,7 @@ describe("wireProblems", () => {
     );
     const problems = found(catalogWith([one]));
 
-    const undeclared = problems.filter((p) => p.kind === "channel-undeclared");
+    const undeclared = problems.filter((p) => p.rule === "channel-undeclared");
     expect(undeclared.map((p) => [p.id, p.peer])).toEqual([
       ["shop.cart.basket.BasketCreated", "shop.cart.basket"],
       ["shop.cart.basket.BasketCheckedOut", "shop.cart.basket"],
@@ -182,7 +184,7 @@ describe("wireProblems", () => {
     );
     const problems = found(catalogWith([one]));
 
-    const promised = problems.filter((p) => p.kind === "channel-unpublished");
+    const promised = problems.filter((p) => p.rule === "channel-unpublished");
     expect(promised.map((p) => p.peer)).toEqual(["shop.cart.wishlist"]);
     expect(promised[0]?.id).toBe("shop.cart");
     expect(promised[0]?.note).toContain("cart.ItemWished");
@@ -202,7 +204,7 @@ describe("wireProblems", () => {
       channel("payments.ledger.payment", "receive payments.PaymentAuthorized"),
     );
     const problems = found(catalogWith([one])).filter(
-      (p) => p.kind === "channel-undeclared" || p.kind === "channel-unpublished",
+      (p) => p.rule === "channel-undeclared" || p.rule === "channel-unpublished",
     );
 
     expect(problems).toEqual([]);
@@ -240,7 +242,7 @@ describe("wireProblems", () => {
     );
     const problems = found(catalogWith([cart(), oms]));
 
-    expect(problems.filter((p) => p.kind === "subscription-unresolved")).toEqual(
+    expect(problems.filter((p) => p.rule === "subscription-unresolved")).toEqual(
       [],
     );
   });
@@ -253,7 +255,7 @@ describe("wireProblems", () => {
     const problems = found(catalogWith([cart(), oms]));
 
     const unresolved = problems.filter(
-      (p) => p.kind === "subscription-unresolved",
+      (p) => p.rule === "subscription-unresolved",
     );
     expect(unresolved.map((p) => [p.service, p.peer])).toEqual([
       ["shop.oms", "billing.InvoiceRaised"],
@@ -270,7 +272,7 @@ describe("wireProblems", () => {
     const subscriber = speaking(service("shop.search", []), subscriberChannel);
 
     const mismatch = found(catalogWith([publisher, subscriber])).find(
-      (problem) => problem.kind === "message-encoding",
+      (problem) => problem.rule === "message-encoding",
     );
     expect(mismatch).toMatchObject({
       severity: "error",

package/src/lib/rules.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import type { Field } from "../catalog";
+import { ruleMark, ruleMarks } from "./rules";
+
+describe("ruleMark", () => {
+  it.each([
+    ["min_len", "1", "≥ 1 chars"],
+    ["max_len", "64", "≤ 64 chars"],
+    ["len", "3", "3 chars"],
+    ["min_items", "1", "≥ 1 items"],
+    ["gt", "0", "> 0"],
+    ["gte", "-1", "≥ -1"],
+    ["lte", "9007199254740993", "≤ 9007199254740993"],
+    ["const", "USD", "= USD"],
+    ["in", "USD, EUR", "one of USD, EUR"],
+    ["not_in", "XXX", "none of XXX"],
+    ["pattern", "^[A-Z]{3}$", "matches ^[A-Z]{3}$"],
+    ["format", "email", "email"],
+    ["multiple_of", "5", "multiple of 5"],
+    ["items.max_len", "64", "each ≤ 64 chars"],
+    ["keys.min_len", "1", "each key ≥ 1 chars"],
+    ["values.gte", "0", "each value ≥ 0"],
+    ["cel", "this.sku != ''", "cel"],
+    // A custom option is shown as written; `true` is the whole of a flag.
+    ["(acme.pii)", "true", "(acme.pii)"],
+    ["(acme.mask).style", "LAST_FOUR", "(acme.mask).style LAST_FOUR"],
+    // A rule the page has no words for yet is still shown, spelled as it came.
+    ["well_formed", "true", "well_formed true"],
+  ])("%s %s reads as %s", (name, value, text) => {
+    expect(ruleMark({ name, value })).toEqual({ text, title: `${name} = ${value}` });
+  });
+
+  it("a bare flag has no value in the title either", () => {
+    expect(ruleMark({ name: "unique" })).toEqual({ text: "unique", title: "unique" });
+    expect(ruleMark({ name: "lt_now" })).toEqual({ text: "in the past", title: "lt_now" });
+  });
+});
+
+describe("ruleMarks", () => {
+  const field = (extra: Partial<Field>): Field => ({ name: "x", type: "string", doc: "", ...extra });
+
+  it("puts required first and keeps the rules in the source's order", () => {
+    const marks = ruleMarks(field({ required: true, rules: [{ name: "max_len", value: "16" }, { name: "format", value: "uuid" }] }));
+    expect(marks.map((m) => m.text)).toEqual(["required", "≤ 16 chars", "uuid"]);
+    expect(marks[0]?.title).toBe("must be sent");
+  });
+
+  it("is empty for a field the source says nothing about", () => {
+    expect(ruleMarks(field({}))).toEqual([]);
+  });
+});

package/src/lib/rules.ts

@@ -0,0 +1,86 @@
+// What a field's rules say, in words a reader scans.
+//
+// A rule arrives as the catalog spells it - `min_len 1`, `items.max_len 64`,
+// `format email` - the same spelling whether a Protovalidate option or a JSON
+// Schema keyword put it there. The page shows each as a short mark beside the
+// type, "≥ 1 chars", and keeps the spelling for the tooltip, which is what
+// a reader copies into a search of the source. A rule the catalog has no
+// words for, a custom option, is shown as it was written rather than hidden.
+
+import type { Field, FieldRule } from "../catalog";
+
+export interface RuleMark {
+  /** The chip: a few words, or the value alone when the value is the point. */
+  text: string;
+  /** The rule as the fragment carries it: `min_len = 1`. */
+  title: string;
+}
+
+/** What a rule on the members of a list or map is about, by its prefix. */
+const OF: Record<string, string> = {
+  items: "each",
+  keys: "each key",
+  values: "each value",
+};
+
+const WORDS: Record<string, (v: string) => string> = {
+  min_len: (v) => `≥ ${v} chars`,
+  max_len: (v) => `≤ ${v} chars`,
+  len: (v) => `${v} chars`,
+  min_items: (v) => `≥ ${v} items`,
+  max_items: (v) => `≤ ${v} items`,
+  min_pairs: (v) => `≥ ${v} entries`,
+  max_pairs: (v) => `≤ ${v} entries`,
+  gt: (v) => `> ${v}`,
+  gte: (v) => `≥ ${v}`,
+  lt: (v) => `< ${v}`,
+  lte: (v) => `≤ ${v}`,
+  const: (v) => `= ${v}`,
+  multiple_of: (v) => `multiple of ${v}`,
+  in: (v) => `one of ${v}`,
+  not_in: (v) => `none of ${v}`,
+  pattern: (v) => `matches ${v}`,
+  prefix: (v) => `starts with ${v}`,
+  suffix: (v) => `ends with ${v}`,
+  contains: (v) => `contains ${v}`,
+  not_contains: (v) => `never contains ${v}`,
+  format: (v) => v,
+  unique: () => "unique",
+  defined_only: () => "a defined value",
+  lt_now: () => "in the past",
+  gt_now: () => "in the future",
+  cel: () => "cel",
+};
+
+/** The mark for one rule. */
+export function ruleMark(rule: FieldRule): RuleMark {
+  const title = rule.value === undefined ? rule.name : `${rule.name} = ${rule.value}`;
+  const value = rule.value ?? "";
+
+  // A custom option keeps its own name; `(acme.pii)` says more than any
+  // words the catalog could put to it.
+  if (rule.name.startsWith("(")) {
+    return { text: value && value !== "true" ? `${rule.name} ${value}` : rule.name, title };
+  }
+
+  const dot = rule.name.indexOf(".");
+  const of = dot > 0 ? OF[rule.name.slice(0, dot)] : undefined;
+  const base = of ? rule.name.slice(dot + 1) : rule.name;
+  const words = WORDS[base];
+  const text = words ? words(value) : value ? `${base} ${value}` : base;
+
+  return { text: of ? `${of} ${text}` : text, title };
+}
+
+/** Every mark a field wears: `required` first, then its rules as written. */
+export function ruleMarks(field: Field): RuleMark[] {
+  const marks: RuleMark[] = [];
+  if (field.required) {
+    marks.push({ text: "required", title: "must be sent" });
+  }
+  for (const rule of field.rules ?? []) {
+    marks.push(ruleMark(rule));
+  }
+
+  return marks;
+}

package/src/lib/shape.test.ts

@@ -211,6 +211,38 @@ describe("schemaChanges", () => {
     expect(removed.map((f) => f.name)).toEqual(["gone"]);
   });
 
+  it("a field whose rules moved is changed, with the rules it had", () => {
+    const rules = {
+      id: "x.y.R",
+      versions: [
+        {
+          version: "v1",
+          fields: [
+            { name: "code", type: "string", doc: "", rules: [{ name: "min_len", value: "8" }] },
+            { name: "who", type: "string", doc: "" },
+            { name: "same", type: "string", doc: "", rules: [{ name: "in", value: "a, b" }, { name: "unique" }] },
+            { name: "both", type: "int32", doc: "", required: true },
+          ],
+        },
+        {
+          version: "v2",
+          fields: [
+            { name: "code", type: "string", doc: "", rules: [{ name: "min_len", value: "12" }] },
+            { name: "who", type: "string", doc: "", required: true, rules: [{ name: "format", value: "uuid" }] },
+            // The same rules in another order are the same rules.
+            { name: "same", type: "string", doc: "", rules: [{ name: "unique" }, { name: "in", value: "a, b" }] },
+            { name: "both", type: "int64", doc: "" },
+          ],
+        },
+      ],
+    } as unknown as Event;
+    const { byField } = schemaChanges(rules, "v2");
+    expect(byField.get("code")).toEqual({ change: "changed", rulesFrom: "≥ 8 chars" });
+    expect(byField.get("who")).toEqual({ change: "changed", rulesFrom: "" });
+    expect(byField.get("same")).toBeUndefined();
+    expect(byField.get("both")).toEqual({ change: "changed", from: "int32", rulesFrom: "required" });
+  });
+
   it("agrees with the fixture: OrderPlaced v2 added channel", () => {
     const placed = eventById("shop.oms.order.OrderPlaced");
     const { byField, removed } = schemaChanges(placed, "v2");