@shortlink-org/portolan 0.3.0 → 0.4.0

package/src/components/ProblemRow.tsx

@@ -1,13 +1,29 @@
-// One problem, as a row: what the near end is, where both ends live, and
-// the words for what is wrong with the edge between them. The problems page
-// lists every one of these; the overview shows the first few.
+// One problem, as a row: the edge, the words for what is wrong with it,
+// where it is met in the flows, and where the code is.
+//
+// The row is light on purpose: under a rule's heading on the Problems page
+// the rule's words are said once, above, and the row is the edge and its
+// note. On its own - the overview shows the first few - it wears the rule's
+// words too, as a link to the rule. The rule's subject says where the near
+// end leads: an event has a page, a table has a canvas, a channel, a call
+// and a deployment are shown on their service's page.
 
 import { Link } from "react-router";
+import { ExternalLink } from "lucide-react";
+import { catalog, index } from "../data";
 import type { Problem } from "../lib/derive";
 import { ctxStyle } from "../lib/context-color";
+import type { Kind } from "../lib/kinds";
 import { staggerStyle } from "../lib/motion";
+import { flowsOfProblem } from "../lib/problem-flows";
+import { useProblemRules } from "../lib/problem-rules";
+import type { RuleSubject } from "../lib/problem-rules";
+import { sourceHref } from "../lib/source-link";
 import {
+  aggregatePath,
   eventPath,
+  flowPath,
+  paths,
   servicePath,
   storePath,
   tablePath,
@@ -17,171 +33,175 @@ import { KindIcon } from "./kind";
 import { Ident } from "./Ident";
 
 /** The icon a problem row carries: what the near end of the edge IS. */
-const KIND_OF: Record<Problem["kind"], "service" | "event" | "table"> = {
-  rpc: "service",
+export const ICON_OF: Record<RuleSubject, Kind> = {
+  service: "service",
+  call: "service",
+  copy: "service",
+  event: "event",
   consumer: "event",
-  "cross-service-fk": "table",
-  "cross-service-lineage": "table",
-  "shared-store": "table",
-  "persistence-drift": "table",
-  "column-type": "table",
-  "outbox-payload": "table",
-  "proto-missing": "service",
-  "proto-drift": "service",
-  "shared-channel": "event",
-  "channel-undeclared": "event",
-  "channel-unpublished": "service",
-  "message-encoding": "service",
-  "subscription-unresolved": "service",
+  channel: "event",
+  subscription: "service",
+  table: "table",
+  column: "table",
+  deployment: "service",
+  flow: "flow",
+  aggregate: "aggregate",
 };
 
-const KIND_NOTE: Record<Problem["kind"], string> = {
-  rpc: "the provider of this call is not in the catalog",
-  consumer: "this consumer of the event is not in the catalog",
-  "cross-service-fk": "foreign key across a service boundary",
-  "cross-service-lineage": "a value copied from another service's schema",
-  "shared-store": "a second service writes this database",
-  "persistence-drift": "this table no longer carries the aggregate it claims",
-  "column-type": "column type and domain type disagree",
-  "outbox-payload": "an outbox with no payload column",
-  "proto-missing":
-    "the provider is in the catalog but answers on no such method",
-  "proto-drift": "the vendored proto and provider schema disagree",
-  "shared-channel": "a second service publishes on this channel",
-  "channel-undeclared":
-    "this event goes out on a channel the service does not declare",
-  "channel-unpublished": "a declared channel no event of this service names",
-  "message-encoding": "publisher and subscriber use different payload encodings",
-  "subscription-unresolved":
-    "nothing in the catalog publishes what this service listens for",
-};
+/** A table or a view, whichever the id turns out to name. */
+function relationPath(id: string): string | null {
+  return tablePath(id) ?? viewPath(id);
+}
+
+/** A column's relation: its id minus the column, which is what the canvas can show. */
+function columnPath(id: string): string | null {
+  return relationPath(id.split(".").slice(0, -1).join("."));
+}
 
-/** Where the near end of a problem lives, by what kind of edge it is. */
-function nearPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "rpc":
-    // The near end is the CALLING service either way. `rpc` is a call whose
-    // peer is nobody; this is a call whose peer is known and whose method is
-    // not - and in both the thing to go and look at is the caller.
-    case "proto-missing":
-    case "proto-drift":
-      return servicePath(problem.service);
+/** Where the near end of a problem lives, by what the rule is about. */
+export function nearPath(over: RuleSubject, problem: Problem): string | null {
+  switch (over) {
+    case "event":
     case "consumer":
-    case "channel-undeclared":
       return eventPath(problem.id);
-    // The near end is an event when the service has one on the channel, and
-    // the service itself when the claim comes from its document alone.
-    case "shared-channel":
-      return eventPath(problem.id) ?? servicePath(problem.service);
-    case "channel-unpublished":
-    case "message-encoding":
-    case "subscription-unresolved":
-      return servicePath(problem.service);
-    case "shared-store":
-    case "persistence-drift":
-    case "outbox-payload":
-      return tablePath(problem.id);
-    // The id is "<relation>.<column>", so the relation is its own id minus the
-    // last segment — and the relation is what the canvas can actually show.
-    case "cross-service-fk":
-    case "column-type":
-      return relationPath(problem.id.split(".").slice(0, -1).join("."));
-    // Lineage is stated on a column, except when a view states it whole, so
-    // the id is one or the other and both are looked up the same way.
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.id) ??
-        relationPath(problem.id.split(".").slice(0, -1).join("."))
-      );
+    // A channel row is an event of the service when it has one on the
+    // address, and the service itself when the claim comes from its document.
+    case "channel":
+      return eventPath(problem.id) ?? (problem.service ? servicePath(problem.service) : null);
+    case "table":
+      return relationPath(problem.id);
+    case "column":
+      return columnPath(problem.id);
+    case "flow":
+      return flowPath(problem.id);
+    case "aggregate":
+      return aggregatePath(problem.id);
+    case "service":
+    case "call":
+    case "copy":
+    case "subscription":
+    case "deployment":
+      return problem.service ? servicePath(problem.service) : null;
   }
 }
 
-/** A table or a view, whichever the id turns out to name. */
-function relationPath(id: string): string | null {
-  return tablePath(id) ?? viewPath(id);
+/** Where the far end lives, when it is the id of something the catalog has. */
+function peerPath(peer: string): string | null {
+  if (!peer) return null;
+  return servicePath(peer) ?? eventPath(peer) ?? relationPath(peer) ?? columnPath(peer) ?? storePath(peer);
 }
 
-/** Where the far end lives, when the catalog knows it. */
-function peerPath(problem: Problem): string | null {
-  switch (problem.kind) {
-    case "cross-service-fk":
-      return tablePath(problem.peer);
-    case "cross-service-lineage":
-      return (
-        relationPath(problem.peer) ??
-        relationPath(problem.peer.split(".").slice(0, -1).join("."))
-      );
-    case "shared-store":
-    case "shared-channel":
-    case "message-encoding":
-      return servicePath(problem.peer);
-    case "outbox-payload":
-      return storePath(problem.peer);
-    default:
-      return null;
-  }
+/** An http(s) URL the note ends with, for a row whose far end is a page elsewhere - the deployer's. */
+function urlIn(note: string | undefined): string | null {
+  const match = note?.match(/https?:\/\/\S+$/);
+  return match ? match[0] : null;
 }
 
-export function ProblemRow({ problem, index }: { problem: Problem; index: number }) {
-  const near = nearPath(problem);
-  const peerTo = peerPath(problem);
-  const tone =
-    problem.severity === "error"
-      ? "var(--status-unresolved)"
-      : "var(--status-declared)";
+const MAX_FLOWS = 4;
+
+export function ProblemRow({
+  problem,
+  index: at,
+  showRule = true,
+}: {
+  problem: Problem;
+  index: number;
+  /** Say which rule made the row. Off under a heading that already says so. */
+  showRule?: boolean;
+}) {
+  const rules = useProblemRules();
+  const rule = rules.find((candidate) => candidate.id === problem.rule);
+  const over = rule?.over ?? "service";
+  const near = nearPath(over, problem);
+  const peerTo = peerPath(problem.peer);
+  const note = rule?.note ?? problem.rule;
+  const service = problem.service ? index.serviceById.get(problem.service) : undefined;
+  const source = problem.source ? sourceHref(problem.source, service) : null;
+  const url = over === "deployment" ? urlIn(problem.note) : null;
+  const text = url && problem.note ? problem.note.slice(0, problem.note.length - url.length).trim() : problem.note;
+  const flows = flowsOfProblem(catalog, index, over, problem);
+  const tone = problem.severity === "error" ? "text-unresolved" : "text-declared";
 
   return (
-    <div
-      className="stagger-in flex flex-wrap items-baseline gap-x-3 gap-y-1 rounded-control border px-3 py-2"
-      style={{ ...staggerStyle(index), borderColor: tone }}
-    >
-      <KindIcon kind={KIND_OF[problem.kind]} />
-      {near ? (
-        <Link
-          to={near}
-          data-nav-item
-          className="mono rounded-control text-accent hover:underline"
-          title={problem.id}
-        >
-          {problem.id}
-        </Link>
-      ) : (
-        <Ident value={problem.id} />
-      )}
-      <span aria-hidden className="text-muted">
-        →
-      </span>
-      {peerTo ? (
-        <Link
-          to={peerTo}
-          className="mono rounded-control hover:underline"
-          style={{ color: tone }}
-          title={problem.peer}
-        >
-          {problem.peer}
-        </Link>
-      ) : (
-        <Ident
-          value={problem.peer}
-          className={
-            problem.severity === "error" ? "text-unresolved" : "text-declared"
-          }
-          title={`${problem.peer} — ${KIND_NOTE[problem.kind]}. Click to copy.`}
-        />
-      )}
-      <span className="chip ctx" style={ctxStyle(problem.context)}>
-        <span aria-hidden className="dot" />
-        {problem.context}
-      </span>
-      <span className="mono ml-auto text-muted">{KIND_NOTE[problem.kind]}</span>
-      {problem.note ? (
-        <p className="w-full border-l-2 pl-2 border-line-strong text-muted">
-          {problem.note}
-        </p>
-      ) : null}
-      {problem.source ? (
-        <div className="mono w-full text-muted">
-          <Ident value={problem.source} />
+    <div className="stagger-in px-3 py-2.5" style={staggerStyle(at)} data-rule={problem.rule}>
+      <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+        <KindIcon kind={ICON_OF[over]} className="self-center" />
+        {near ? (
+          <Link to={near} data-nav-item className="mono rounded-control text-accent hover:underline" title={problem.id}>
+            {problem.id}
+          </Link>
+        ) : (
+          <Ident value={problem.id} />
+        )}
+        {/* A rule may name no far end; then there is no arrow to draw. */}
+        {problem.peer ? (
+          <>
+            <span aria-hidden className="text-faint">
+              →
+            </span>
+            {peerTo ? (
+              <Link to={peerTo} className={`mono rounded-control hover:underline ${tone}`} title={problem.peer}>
+                {problem.peer}
+              </Link>
+            ) : (
+              <Ident value={problem.peer} className={tone} title={`${problem.peer} — ${note}. Click to copy.`} />
+            )}
+          </>
+        ) : null}
+        {problem.context ? (
+          <span className="chip ctx" style={ctxStyle(problem.context)}>
+            <span aria-hidden className="dot" />
+            {problem.context}
+          </span>
+        ) : null}
+        {showRule ? (
+          <Link
+            to={`${paths.settingsRules()}#rule-${problem.rule}`}
+            className="mono ml-auto max-w-[45%] truncate rounded-control text-muted hover:text-ink hover:underline"
+            title={`rule ${problem.rule}${rule?.action ? ` — ${rule.action}` : ""}`}
+          >
+            {note}
+          </Link>
+        ) : null}
+      </div>
+      {text ? <p className="mt-1 max-w-prose text-muted">{text}</p> : null}
+      {flows.length > 0 || source || url ? (
+        <div className="mono mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1 text-muted">
+          {flows.length > 0 ? (
+            <span className="flex flex-wrap items-center gap-1">
+              <span className="text-faint">in</span>
+              {flows.slice(0, MAX_FLOWS).map((hit) => (
+                <Link
+                  key={hit.flow.id}
+                  to={hit.stepId ? paths.flowStep(hit.flow.slug, hit.stepId) : paths.flow(hit.flow.slug)}
+                  className="chip border-line-strong hover:border-accent hover:text-accent"
+                  title={hit.stepId ? `${hit.flow.name}, step ${hit.number}` : hit.flow.name}
+                >
+                  {hit.flow.name}
+                  {hit.number ? <span className="text-faint">·{hit.number}</span> : null}
+                </Link>
+              ))}
+              {flows.length > MAX_FLOWS ? (
+                <span className="text-faint" title={flows.slice(MAX_FLOWS).map((hit) => hit.flow.name).join(", ")}>
+                  +{flows.length - MAX_FLOWS}
+                </span>
+              ) : null}
+            </span>
+          ) : null}
+          {problem.source ? (
+            source ? (
+              <a href={source} target="_blank" rel="noreferrer" className="truncate rounded-control text-accent hover:underline" title={problem.source}>
+                {problem.source} ↗
+              </a>
+            ) : (
+              <Ident value={problem.source} className="truncate" />
+            )
+          ) : null}
+          {url ? (
+            <a href={url} target="_blank" rel="noreferrer" className="flex items-center gap-1 rounded-control text-accent hover:underline">
+              <ExternalLink size={12} aria-hidden /> open in the deployer
+            </a>
+          ) : null}
         </div>
       ) : null}
     </div>

package/src/components/RuleMarks.tsx

@@ -0,0 +1,22 @@
+// What the source says a field's value must satisfy, as marks beside the
+// type: "required", "≥ 1 chars", "one of USD, EUR". One component so the
+// schema table, the field tree and the inline shape of a request say it the
+// same way; the words come from lib/rules.
+
+import type { Field } from "../catalog";
+import { ruleMarks } from "../lib/rules";
+
+export function RuleMarks({ field }: { field: Field }) {
+  const marks = ruleMarks(field);
+  if (marks.length === 0) return null;
+
+  return (
+    <>
+      {marks.map((mark) => (
+        <span key={mark.title} className="type-mark rule-mark" title={mark.title}>
+          {mark.text}
+        </span>
+      ))}
+    </>
+  );
+}

package/src/components/ShapeRows.tsx

@@ -10,6 +10,7 @@ import { Fragment, useState } from "react";
 import { ChevronDown, ChevronRight } from "lucide-react";
 import type { Field, RpcEnum } from "../catalog";
 import { parseType } from "../lib/shape";
+import { RuleMarks } from "./RuleMarks";
 
 /**
  * The enum a field's type names, among the ones the interface declares. By
@@ -91,26 +92,29 @@ export function ShapeRows({
                 primitive, so a reader can tell which names are worth following
                 without the row becoming a link it is not. */}
             <td className="mono py-0.5 pr-3 whitespace-nowrap text-muted">
-              {set ? (
-                <button
-                  type="button"
-                  onClick={() => toggle(field.name)}
-                  aria-expanded={shown}
-                  className="inline-flex items-center gap-1 rounded-control hover:text-ink"
-                  title={`${set.name}: ${set.values.length} values — click to ${shown ? "hide" : "show"} them`}
-                >
-                  {shown ? (
-                    <ChevronDown size={11} aria-hidden />
-                  ) : (
-                    <ChevronRight size={11} aria-hidden />
-                  )}
-                  {field.type}
-                </button>
-              ) : field.ref ? (
-                `${field.type} →`
-              ) : (
-                field.type
-              )}
+              <span className="inline-flex items-center gap-1.5">
+                {set ? (
+                  <button
+                    type="button"
+                    onClick={() => toggle(field.name)}
+                    aria-expanded={shown}
+                    className="inline-flex items-center gap-1 rounded-control hover:text-ink"
+                    title={`${set.name}: ${set.values.length} values — click to ${shown ? "hide" : "show"} them`}
+                  >
+                    {shown ? (
+                      <ChevronDown size={11} aria-hidden />
+                    ) : (
+                      <ChevronRight size={11} aria-hidden />
+                    )}
+                    {field.type}
+                  </button>
+                ) : field.ref ? (
+                  `${field.type} →`
+                ) : (
+                  field.type
+                )}
+                <RuleMarks field={field} />
+              </span>
             </td>
             <td className="py-0.5 text-muted">{field.doc}</td>
           </tr>

package/src/data.ts

@@ -63,6 +63,22 @@ export const activeCatalogProfile = catalogProfileNamed(
 
 export const activeCatalogDocs = catalogDocs(manifestJson, activeCatalogProfile.id, import.meta.env.BASE_URL);
 
+// The manifest is imported, so a change to it would reload the page - and
+// the page changes it: keeping a recording widens a verify step, adding a
+// project appends one. Neither touches what this module derived from it (the
+// profiles: which sources make which catalog), and in local mode the setup
+// itself is read from the server, not from here. So the update is taken
+// without a reload unless the profiles did change, in which case the reload
+// is the right answer and is asked for.
+if (import.meta.hot) {
+  const profileKey = (m: CatalogProfileManifest & { sources?: string[] }) =>
+    JSON.stringify(profilesFromManifest(m).map((p) => [p.id, p.sources, p.contexts]));
+  import.meta.hot.accept("../portolan.json", (next) => {
+    const incoming = (next as { default?: CatalogProfileManifest & { sources?: string[] } } | undefined)?.default;
+    if (!incoming || profileKey(incoming) !== profileKey(manifest)) import.meta.hot?.invalidate();
+  });
+}
+
 /**
  * Where sources are looked for. The patterns are written out because
  * import.meta.glob resolves at build time and needs literals - and because
@@ -78,6 +94,7 @@ export const SOURCE_GLOBS = [
   "examples/*/*/*/portolan/*.json",
   "vendor/repos/*/*/git.repo.json",
   "vendor/repos/**/portolan/*.json",
+  "examples/argocd/argocd.apps.json",
 ] as const;
 
 const modules: Record<string, unknown> = {
@@ -103,6 +120,10 @@ const modules: Record<string, unknown> = {
     eager: true,
     import: "default",
   }),
+  ...import.meta.glob("../examples/argocd/argocd.apps.json", {
+    eager: true,
+    import: "default",
+  }),
 };
 
 /** What the app draws when the catalog cannot be trusted: nothing. */

package/src/enrich.test.ts

@@ -11,11 +11,14 @@ import type {
   Service,
   Status,
 } from "./catalog";
-import { validateCatalog, walkSteps } from "./catalog";
+import { buildIndex, validateCatalog, walkSteps } from "./catalog";
 import { enrichCatalog } from "./enrich";
 import { contextMap } from "./lib/context-map";
 import { mergeCatalogs } from "./merge";
-import { problems } from "./lib/derive";
+import { builtinProblems } from "./lib/problem-rules";
+
+// The unresolved edges, as the two shipped rules about them find them.
+const problems = (of: Catalog) => builtinProblems(of, buildIndex(of), ["rpc", "consumer"]);
 
 // ---------------------------------------------------------------------------
 // A tiny estate: two services, one event, one method, and whatever flow the
@@ -479,6 +482,92 @@ describe("enrichCatalog: HTTP route correlation", () => {
     ]);
   });
 
+  // The same two providers, and now the manifests say which name each one
+  // answers on. The host the call names decides between them; a host nobody
+  // answers on decides nothing.
+  it("lets the manifests decide between two providers of one route", () => {
+    const toHost = (host: string): Service["consumes"][number] => ({
+      id: `http-client/POST /foo @ ${host}`,
+      peer: host.replace(".", "-"),
+      status: "unresolved",
+      source: "client.go:11",
+      destination: {
+        callSite: "client.go:11",
+        endpointExpression: "path",
+        method: "POST",
+        localPath: "/foo",
+        fullPath: "/foo",
+        serviceDiscoveryAlias: host,
+      },
+    });
+    const caller = service("shop", "oms", {
+      consumes: [
+        toHost("payments.internal"),
+        toHost("ledger.internal"),
+        toHost("nobody.internal"),
+      ],
+    });
+    const payments = {
+      ...httpProvider("payments", "pay", "/foo"),
+      hosts: ["payments", "payments.internal"],
+    };
+    const ledger = {
+      ...httpProvider("ledger", "post", "/foo"),
+      hosts: ["ledger.internal"],
+    };
+
+    const out = enrichCatalog(estate([], [caller, payments, ledger])).catalog;
+    expect(
+      serviceOf(out, "shop.oms").consumes.map((call) => [
+        call.id,
+        call.peer,
+        call.status,
+        call.destination?.resolution?.basis,
+      ]),
+    ).toEqual([
+      ["api/pay", "shop.payments", "declared", "kubernetes-host"],
+      ["api/post", "shop.ledger", "declared", "kubernetes-host"],
+      [
+        "http-client/POST /foo @ nobody.internal",
+        "nobody-internal",
+        "unresolved",
+        undefined,
+      ],
+    ]);
+  });
+
+  it("uses what the caller dials when the call names no host", () => {
+    const caller = service("shop", "oms", {
+      consumes: [
+        {
+          id: "http-client/POST /foo",
+          peer: "http-peer",
+          status: "unresolved",
+          source: "client.go:10",
+        },
+      ],
+      dials: ["ledger.payments.svc"],
+    });
+    const payments = {
+      ...httpProvider("payments", "pay", "/foo"),
+      hosts: ["payments.shop.svc"],
+    };
+    const ledger = {
+      ...httpProvider("ledger", "post", "/foo"),
+      hosts: ["ledger.payments.svc"],
+    };
+
+    const out = enrichCatalog(estate([], [caller, payments, ledger])).catalog;
+    expect(
+      serviceOf(out, "shop.oms").consumes.map((call) => [
+        call.id,
+        call.peer,
+        call.status,
+        call.destination?.resolution?.basis,
+      ]),
+    ).toEqual([["api/post", "shop.ledger", "declared", "kubernetes-host"]]);
+  });
+
   it("resolves a destination-qualified route like a bare one", () => {
     const caller = service("shop", "oms", {
       consumes: [
@@ -1038,7 +1127,7 @@ describe("enrichCatalog: consumers from event steps", () => {
       ["risk", "unresolved"],
       ["ghost.svc", "unresolved"],
     ]);
-    expect(problems(catalog).map((p) => [p.kind, p.peer])).toEqual([
+    expect(problems(catalog).map((p) => [p.rule, p.peer])).toEqual([
       ["consumer", "risk"],
       ["consumer", "ghost.svc"],
     ]);
@@ -1677,6 +1766,41 @@ describe("enrichCatalog: a foreign key into another service's table", () => {
     expect(keyOf(enrichCatalog(catalog).catalog)).toBe("orders");
   });
 
+  it("tells two tables of one name apart by who the referencing service talks to", () => {
+    // The delivery service calls the order service; an unrelated shop in
+    // the same estate has an `orders` table too.
+    const catalog = estateWithStores();
+    catalog.contexts.push(
+      context("delivery", [
+        service("delivery", "core", {
+          consumes: [{ id: "oms.v1.Orders/GetOrder", peer: "shop.oms", status: "declared", source: "x" }],
+        }),
+      ]),
+      context("commerce", [service("commerce", "bagisto")]),
+    );
+    catalog.stores!.push({
+      id: "commerce.bagisto.db",
+      slug: "db",
+      name: "Bagisto database",
+      kind: "mysql",
+      owner: "commerce.bagisto",
+      tables: [{ id: "commerce.bagisto.db.orders", name: "orders", columns: [] }],
+    });
+
+    expect(keyOf(enrichCatalog(catalog).catalog)).toBe("shop.oms.pg.orders");
+  });
+
+  it("prefers a table of the store's own before looking across the estate", () => {
+    const catalog = estateWithStores();
+    catalog.stores![0]!.tables.push({
+      id: "delivery.core.pg.orders",
+      name: "orders",
+      columns: [{ name: "id", type: "text", nullable: false, pk: true }],
+    });
+
+    expect(keyOf(enrichCatalog(catalog).catalog)).toBe("delivery.core.pg.orders");
+  });
+
   it("leaves a key that already resolves untouched, and enriching twice changes nothing", () => {
     const once = enrichCatalog(estateWithStores()).catalog;
     const twice = enrichCatalog(once).catalog;