@shortlink-org/portolan 0.1.0

package/src/er/spec.ts

@@ -0,0 +1,426 @@
+// What an ER canvas draws, worked out before anything is rendered.
+//
+// Pure, like lib/context-map.ts: a store in, nodes and edges out. The canvas
+// component then only positions and paints what this decided, which is what
+// makes "which columns does a collapsed table show?" a question with a test
+// rather than a question with a screenshot.
+//
+// A canvas carries two kinds of card and two kinds of edge. Tables and views
+// are both relations with columns, so they are drawn alike and told apart by
+// their header; foreign keys and lineage are both lines between columns, so
+// they are drawn alike and told apart by their direction and their dash. The
+// difference that matters is what a reader can conclude: a key says a row
+// points at a row, lineage says a value was copied from a value.
+
+import type {
+  CatalogIndex,
+  Column,
+  Store,
+  Table,
+  View,
+} from "../catalog";
+import {
+  columnNameOfId,
+  relationOfColumnId,
+  storeViews,
+  viewReads,
+} from "../catalog";
+import { lineageEdgeId } from "./lineage";
+
+/** Header, one row, and the "+n more" footer, in px. Layout needs the height. */
+export const HEADER_H = 28;
+export const ROW_H = 18;
+export const MORE_H = 16;
+const TABLE_W = 208;
+
+/**
+ * Rows drawn before a card starts scrolling inside itself. Twelve is where a
+ * card stops being a shape you can take in at a glance and becomes a list you
+ * have to read; past that the canvas is better served by a shorter card and a
+ * detail panel than by a taller one.
+ */
+export const MAX_ROWS = 12;
+
+/** How much of a table is on show. */
+export type ColumnMode = "keys" | "all";
+
+/** A card is a table or a view; everything else about them is the same. */
+export type ErNodeKind = "table" | "view";
+
+export interface ErNode {
+  id: string;
+  kind: ErNodeKind;
+  name: string;
+  doc: string | null;
+  /** The table, when this card is one. Exactly one of these two is set. */
+  table: Table | null;
+  /** The view, when this card is one. */
+  view: View | null;
+  store: Store;
+  /** Every column the relation has, in declaration order. */
+  columns: Column[];
+  /** The columns actually drawn, in declaration order. */
+  rows: Column[];
+  /** Columns left out, summarised as "+n more". */
+  hidden: number;
+  /** True when `rows` is longer than the card can show without scrolling. */
+  scrolls: boolean;
+  /** The aggregate this relation holds or presents, if it names one. */
+  aggregate: string | null;
+  /** The context that owns that aggregate — the header tint, and nothing else. */
+  context: string | null;
+  /** A store the service reads but does not own. */
+  ghost: boolean;
+  /** The word on the header chip: "root", "outbox", "view", "matview". */
+  badge: string | null;
+  width: number;
+  height: number;
+}
+
+/**
+ * What a line between two cards means.
+ *
+ * "fk" is a constraint the database enforces and is drawn child → parent, with
+ * the crow's foot at the child. "lineage" is a copy the database performs and
+ * is drawn source → derived, with a plain arrow: it is a direction of travel,
+ * not a cardinality, and drawing it with the same marks would say the view
+ * constrains the table it reads.
+ */
+export type ErEdgeKind = "fk" | "lineage";
+
+export interface ErEdge {
+  id: string;
+  kind: ErEdgeKind;
+  /** Relation ids. For "fk", `from` holds the key, so it is the many end. */
+  from: string;
+  to: string;
+  /** Null on a lineage edge that only knows the relation it reads. */
+  fromColumn: string | null;
+  toColumn: string | null;
+  /** Printed on the edge only when it is not the database's default. */
+  onDelete: string | null;
+  /** True when the two relations are owned by different services. */
+  cross: boolean;
+}
+
+export interface ErSpec {
+  nodes: ErNode[];
+  edges: ErEdge[];
+}
+
+/**
+ * `on delete no action` is what a database does when nothing says otherwise, so
+ * printing it on an edge adds a word and no fact. Anything else changes what
+ * deleting the parent row means, and that belongs on the picture.
+ */
+function shownOnDelete(onDelete: string | undefined): string | null {
+  if (!onDelete) return null;
+  const normalised = onDelete.trim().toLowerCase().replace(/\s+/g, " ");
+  return normalised === "no action" || normalised === "restrict"
+    ? null
+    : onDelete;
+}
+
+export interface ErOptions {
+  mode: ColumnMode;
+  /** Tables the reader has opened by hand; they show every column. */
+  expanded?: ReadonlySet<string>;
+  /** Stores the service reads rather than owns, drawn ghosted. */
+  ghost?: boolean;
+  /** Views on the canvas. On by default — a schema is what the reader asked for. */
+  views?: boolean;
+  /** Lineage edges. On by default, and off is a legible picture, not a broken one. */
+  lineage?: boolean;
+}
+
+/** Anything with columns and an id: a table or a view, asked the same question. */
+type Relation = { id: string; columns: Column[] };
+
+/**
+ * The columns a card shows. Keys-only is the default because a foreign key is
+ * the only column that says anything about the table NEXT to this one, and the
+ * canvas is a picture of what points at what — the rest is detail the panel
+ * holds. A derived column counts as a key for this purpose: it is the one thing
+ * on a view that joins it to anything else, and a view whose every column were
+ * hidden would be a card with a name and nothing under it.
+ *
+ * A relation with none of those still shows its first rows rather than an empty
+ * card: a lookup table with no constraints is still a shape.
+ */
+export function visibleColumns(
+  relation: Relation,
+  options: ErOptions,
+): Column[] {
+  if (options.mode === "all" || options.expanded?.has(relation.id)) {
+    return relation.columns;
+  }
+  const joined = relation.columns.filter(
+    (c) => c.pk || c.fk || (c.from?.length ?? 0) > 0,
+  );
+  return joined.length > 0 ? joined : relation.columns.slice(0, 3);
+}
+
+export function nodeHeight(rows: number, hidden: number): number {
+  return (
+    HEADER_H + Math.min(rows, MAX_ROWS) * ROW_H + (hidden > 0 ? MORE_H : 0)
+  );
+}
+
+const ROLE_BADGE: Record<string, string> = {
+  "aggregate-root": "root",
+  child: "child",
+  outbox: "outbox",
+  projection: "projection",
+  lookup: "lookup",
+};
+
+/** One store's canvas. Relations in catalog order; layout decides where they land. */
+export function erSpec(
+  index: CatalogIndex,
+  store: Store,
+  options: ErOptions,
+): ErSpec {
+  const showViews = options.views ?? true;
+  const showLineage = options.lineage ?? true;
+
+  /** The context that owns an aggregate, which is all the tint ever reads. */
+  const contextOf = (aggregate: string | null): string | null => {
+    const owner = aggregate ? index.aggregateOwner.get(aggregate) : undefined;
+    return owner ? (index.serviceContext.get(owner.id)?.id ?? null) : null;
+  };
+
+  const card = (
+    id: string,
+    kind: ErNodeKind,
+    name: string,
+    doc: string | undefined,
+    columns: Column[],
+    aggregate: string | null,
+    badge: string | null,
+    table: Table | null,
+    view: View | null,
+  ): ErNode => {
+    const rows = visibleColumns({ id, columns }, options);
+    const hidden = columns.length - rows.length;
+    return {
+      id,
+      kind,
+      name,
+      doc: doc ?? null,
+      table,
+      view,
+      store,
+      columns,
+      rows,
+      hidden,
+      scrolls: rows.length > MAX_ROWS,
+      aggregate,
+      context: contextOf(aggregate),
+      ghost: options.ghost ?? false,
+      badge,
+      width: TABLE_W,
+      height: nodeHeight(rows.length, hidden),
+    };
+  };
+
+  const nodes: ErNode[] = store.tables.map((table) =>
+    card(
+      table.id,
+      "table",
+      table.name,
+      table.doc,
+      table.columns,
+      table.persists?.aggregate ?? null,
+      ROLE_BADGE[table.role ?? "other"] ?? null,
+      table,
+      null,
+    ),
+  );
+
+  if (showViews) {
+    for (const view of storeViews(store)) {
+      nodes.push(
+        card(
+          view.id,
+          "view",
+          view.name,
+          view.doc,
+          view.columns,
+          view.persists?.aggregate ?? null,
+          view.materialized ? "matview" : "view",
+          null,
+          view,
+        ),
+      );
+    }
+  }
+
+  const own = new Set(nodes.map((n) => n.id));
+  const edges: ErEdge[] = [];
+
+  for (const table of store.tables) {
+    for (const column of table.columns) {
+      const fk = column.fk;
+      if (!fk) continue;
+      // An edge is drawn only when both ends are on this canvas. A key into
+      // another service's store is a fact about the boundary, not about this
+      // picture, and the Problems page is where it is answered.
+      if (!own.has(fk.table)) continue;
+      const target = index.tableById.get(fk.table);
+      edges.push({
+        id: `${table.id}.${column.name}->${fk.table}.${fk.column}`,
+        kind: "fk",
+        from: table.id,
+        to: fk.table,
+        fromColumn: column.name,
+        toColumn: fk.column,
+        onDelete: shownOnDelete(fk.onDelete),
+        cross: target ? target.store.owner !== store.owner : false,
+      });
+    }
+  }
+
+  if (showLineage) {
+    /** Relations already joined by a column-level edge, so `reads` can skip them. */
+    const joined = new Set<string>();
+    for (const node of nodes) {
+      for (const column of node.columns) {
+        for (const ref of column.from ?? []) {
+          const source = relationOfColumnId(ref);
+          if (!own.has(source) || source === node.id) continue;
+          joined.add(`${source}->${node.id}`);
+          const from = index.tableById.get(source) ?? index.viewById.get(source);
+          edges.push({
+            id: lineageEdgeId(ref, `${node.id}.${column.name}`),
+            kind: "lineage",
+            from: source,
+            to: node.id,
+            fromColumn: columnNameOfId(ref),
+            toColumn: column.name,
+            onDelete: null,
+            cross: from ? from.store.owner !== store.owner : false,
+          });
+        }
+      }
+    }
+
+    // A view that says what it reads but not which column fed which is still
+    // telling the reader something they cannot get anywhere else, so it gets a
+    // line — one per pair, drawn card to card rather than row to row.
+    for (const node of nodes) {
+      if (!node.view) continue;
+      for (const readId of viewReads(node.view)) {
+        if (!own.has(readId) || readId === node.id) continue;
+        if (joined.has(`${readId}->${node.id}`)) continue;
+        joined.add(`${readId}->${node.id}`);
+        edges.push({
+          id: lineageEdgeId(readId, node.id),
+          kind: "lineage",
+          from: readId,
+          to: node.id,
+          fromColumn: null,
+          toColumn: null,
+          onDelete: null,
+          cross: false,
+        });
+      }
+    }
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * Foreign keys leaving this store. They are not edges — there is nothing on
+ * the canvas to point at — so they are listed under the store header instead,
+ * where "this schema is not self-contained" can actually be read.
+ */
+export interface ErOutbound {
+  from: string;
+  fromColumn: string;
+  to: string;
+  /** The service that owns the far end. */
+  peer: string;
+}
+
+export function outboundKeys(
+  index: CatalogIndex,
+  store: Store,
+): ErOutbound[] {
+  const own = new Set(store.tables.map((t) => t.id));
+  const out: ErOutbound[] = [];
+  for (const table of store.tables) {
+    for (const column of table.columns) {
+      const fk = column.fk;
+      if (!fk || own.has(fk.table)) continue;
+      const target = index.tableById.get(fk.table);
+      out.push({
+        from: table.id,
+        fromColumn: column.name,
+        to: fk.table,
+        peer: target?.store.owner ?? "unknown",
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Columns this store copies from somewhere else. The same shape as an outbound
+ * key and for the same reason — the far end is not on the canvas — but a
+ * different sentence: a key that leaves the store is a constraint nobody can
+ * enforce, a value that comes in from another store is a copy nobody is told
+ * to refresh.
+ */
+export function outboundLineage(
+  index: CatalogIndex,
+  store: Store,
+): ErOutbound[] {
+  const own = new Set<string>([
+    ...store.tables.map((t) => t.id),
+    ...storeViews(store).map((v) => v.id),
+  ]);
+  const out: ErOutbound[] = [];
+  const relations: { id: string; columns: Column[] }[] = [
+    ...store.tables,
+    ...storeViews(store),
+  ];
+  for (const relation of relations) {
+    for (const column of relation.columns) {
+      for (const ref of column.from ?? []) {
+        const source = relationOfColumnId(ref);
+        if (own.has(source)) continue;
+        const target =
+          index.tableById.get(source) ?? index.viewById.get(source);
+        out.push({
+          from: relation.id,
+          fromColumn: column.name,
+          to: ref,
+          peer: target?.store.owner ?? "unknown",
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Cards matching a search term, by name, column name, or the aggregate they
+ * hold. Returns ids so the canvas can light them without re-deriving anything.
+ */
+export function matchingNodes(spec: ErSpec, term: string): Set<string> {
+  const needle = term.trim().toLowerCase();
+  if (!needle) return new Set();
+  const out = new Set<string>();
+  for (const node of spec.nodes) {
+    const hay = [
+      node.name,
+      node.aggregate ?? "",
+      node.doc ?? "",
+      node.view?.definition ?? "",
+      ...node.columns.map((c) => c.name),
+    ];
+    if (hay.some((h) => h.toLowerCase().includes(needle))) out.add(node.id);
+  }
+  return out;
+}

package/src/flow/ChainList.tsx

@@ -0,0 +1,162 @@
+// The "then what" tree, drawn in the rail's own vocabulary: an indented row per
+// node, a status square at the end of every row, and the corner arrow the rail
+// uses for "continues in". Every row links to the thing it names, and a receipt
+// or a published event links to the step it was read from.
+
+import { Link } from "react-router";
+import { CornerDownRight } from "lucide-react";
+
+import { statusVar } from "../components/primitives";
+import { ctxStyle } from "../lib/context-color";
+import { plural } from "../lib/format";
+import { eventPath, paths, servicePath } from "../routes";
+import { CHAIN_BUDGET } from "./chain";
+import type { ChainCut, ChainNode, EventChain } from "./chain";
+
+const indent = (depth: number) => 8 + depth * 12;
+
+export function ChainList({ chain }: { chain: EventChain }) {
+  return (
+    <div className="flex flex-col" data-nav-list>
+      {chain.nodes.map((node, i) => (
+        <Row key={`${i}`} node={node} path={`${i}`} />
+      ))}
+      {chain.truncated ? (
+        <div
+          className="mono py-0.5 text-muted"
+          style={{ paddingLeft: indent(0) }}
+          title={`the walk stops at ${CHAIN_BUDGET} rows`}
+        >
+          … and more than fits here
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function Row({ node, path }: { node: ChainNode; path: string }) {
+  return (
+    <>
+      <div
+        className="flex items-start gap-2 py-0.5 pr-2"
+        style={{ paddingLeft: indent(node.depth) }}
+      >
+        <Label node={node} />
+        <span
+          aria-hidden
+          className="mt-1.5 ml-auto size-1.5 shrink-0 rounded-[1px]"
+          style={{ background: statusVar(node.status) }}
+          title={
+            node.worst === node.status
+              ? node.status
+              : `${node.status}; ${node.worst} further down`
+          }
+        />
+      </div>
+      {node.kind === "consumer" && node.known && node.children.length === 0 ? (
+        <Aside depth={node.depth + 1}>no flow shows this service hearing it</Aside>
+      ) : null}
+      {node.children.map((child, i) => (
+        <Row key={`${path}.${i}`} node={child} path={`${path}.${i}`} />
+      ))}
+      {node.cut ? <Cut cut={node.cut} depth={node.depth + 1} /> : null}
+    </>
+  );
+}
+
+function Label({ node }: { node: ChainNode }) {
+  switch (node.kind) {
+    case "consumer": {
+      const to = servicePath(node.service);
+      return (
+        <span className="mono flex min-w-0 flex-wrap items-center gap-1.5">
+          {to ? (
+            <Link to={to} data-nav-item className="rounded-control text-accent">
+              {node.service}
+            </Link>
+          ) : (
+            <span className="text-unresolved" title="no service in the catalog answers to this name">
+              {node.service}
+            </span>
+          )}
+          {node.context ? <ContextChip id={node.context} /> : null}
+          {node.via ? (
+            <span
+              className="text-muted"
+              title={`read from flow ${node.via.flow}, step ${node.via.step}; no source declares it`}
+            >
+              via flow
+            </span>
+          ) : null}
+        </span>
+      );
+    }
+    case "receipt":
+      return (
+        <Link
+          to={paths.flowStep(node.flow, node.stepId)}
+          data-nav-item
+          className="mono flex min-w-0 items-center gap-1 rounded-control text-accent hover:underline"
+          title={`the step where it hears the event, in ${node.name}`}
+        >
+          <CornerDownRight size={9} aria-hidden className="shrink-0" />
+          <span className="truncate">
+            in {node.name} · step {node.number}
+          </span>
+        </Link>
+      );
+    case "event": {
+      const to = eventPath(node.id);
+      return (
+        <span className="mono flex min-w-0 flex-wrap items-center gap-1.5">
+          <span className="text-muted">publishes</span>
+          {to ? (
+            <Link to={to} data-nav-item className="rounded-control text-accent">
+              {node.name}
+            </Link>
+          ) : (
+            <span>{node.name}</span>
+          )}
+          {node.context ? <ContextChip id={node.context} /> : null}
+          <Link
+            to={paths.flowStep(node.flow, node.stepId)}
+            className="text-muted hover:text-ink hover:underline"
+            title="the step it is published at"
+          >
+            step {node.number}
+          </Link>
+        </span>
+      );
+    }
+  }
+}
+
+function ContextChip({ id }: { id: string }) {
+  return (
+    <span className="chip ctx" style={ctxStyle(id)}>
+      <span aria-hidden className="dot" />
+      {id}
+    </span>
+  );
+}
+
+function Aside({ depth, children }: { depth: number; children: string }) {
+  return (
+    <div className="mono py-0.5 text-muted" style={{ paddingLeft: indent(depth) }}>
+      {children}
+    </div>
+  );
+}
+
+function Cut({ cut, depth }: { cut: ChainCut; depth: number }) {
+  const n = cut.hidden;
+  const text =
+    cut.reason === "cycle"
+      ? "already on this path — the chain comes back around"
+      : cut.reason === "seen"
+        ? "followed above"
+        : cut.reason === "depth"
+        ? `${n} ${plural(n, "consumer")} further down, past the depth this page follows`
+        : `and ${n} more`;
+  return <Aside depth={depth}>{text}</Aside>;
+}

package/src/flow/FlowTable.tsx

@@ -0,0 +1,123 @@
+// Compact mode: the same sequence, as a table.
+//
+// The rail is for reading a flow in order. This is for the other question —
+// "which steps are unresolved", "what does payments touch", "give me the list"
+// — and that question wants columns, sorting, filtering and an export, all of
+// which the app already has exactly once. So compact mode is not a narrower
+// rail; it is the flow handed to the same DataTable every index page uses.
+
+import { useMemo } from "react";
+import type { Flow, Status, Step } from "../catalog";
+import { contextName } from "../lib/context-color";
+import { flowStepId } from "../selection/model";
+import { DataTable } from "../table/DataTable";
+import type { ColumnSpec } from "../table/types";
+import type { Chapter } from "./chapters";
+import type { OutlineStep } from "./outline";
+
+interface Row {
+  id: string;
+  number: number;
+  step: string;
+  route: string;
+  kind: string;
+  status: Status;
+  note: string | undefined;
+  chapter: string;
+  /** Not a column: what the row's selection lights up elsewhere. */
+  selection: string;
+}
+
+const COLUMNS: ColumnSpec<Row>[] = [
+  { id: "number", header: "#", type: "number", value: (r) => r.number, size: 56 },
+  {
+    id: "step",
+    header: "step",
+    type: "text",
+    value: (r) => r.step,
+    primary: true,
+    size: 260,
+  },
+  {
+    id: "route",
+    header: "from → to",
+    type: "mono",
+    value: (r) => r.route,
+    size: 300,
+  },
+  { id: "kind", header: "kind", type: "text", value: (r) => r.kind, facet: true, size: 96 },
+  {
+    id: "status",
+    header: "status",
+    type: "status",
+    value: (r) => r.status,
+    facet: true,
+    size: 128,
+  },
+  {
+    id: "chapter",
+    header: "chapter",
+    type: "text",
+    // Not offered as a chip-set: a chapter is named by its condition, and a
+    // toolbar of fifteen sentences is taller than the table it filters. The
+    // text filter reaches them, and the rail is where chapters are navigated.
+    value: (r) => r.chapter,
+    size: 220,
+  },
+  { id: "note", header: "note", type: "text", value: (r) => r.note, size: 320 },
+];
+
+/** The two participants, with the context each sits in when it has one. */
+function route(step: Step, contextOf: (id: string) => string | null): string {
+  const name = (id: string): string => {
+    const context = contextOf(id);
+    return context ? `${id} (${contextName(context)})` : id;
+  };
+  return step.from === step.to
+    ? `${name(step.from)} ↺`
+    : `${name(step.from)} → ${name(step.to)}`;
+}
+
+export function FlowTable({
+  flow,
+  rows,
+  chapters,
+  contextOf,
+}: {
+  flow: Flow;
+  /** The rail's step rows, so the table shows exactly what the rail shows. */
+  rows: readonly OutlineStep[];
+  chapters: readonly Chapter[];
+  contextOf: (participantId: string) => string | null;
+}) {
+  const data = useMemo<Row[]>(() => {
+    const chapterOf = new Map<string, string>();
+    for (const chapter of chapters) {
+      for (const stepId of chapter.stepIds) chapterOf.set(stepId, chapter.title);
+    }
+    return rows.map(({ step, number }) => ({
+      id: step.id,
+      number,
+      step: step.label ?? step.ref ?? step.kind,
+      route: route(step, contextOf),
+      kind: step.kind,
+      status: step.status,
+      note: step.note,
+      chapter: chapterOf.get(step.id) ?? "—",
+      selection: flowStepId(flow.slug, step.id),
+    }));
+  }, [rows, chapters, contextOf, flow.slug]);
+
+  return (
+    <DataTable
+      tableId={`flow-steps:${flow.slug}`}
+      columns={COLUMNS}
+      rows={data}
+      rowId={(row) => row.id}
+      defaultSort={[{ id: "number", desc: false }]}
+      selectionId={(row) => row.selection}
+      caption={`${flow.name} — steps`}
+      empty="no step survives the filters on this view"
+    />
+  );
+}