@shortlink-org/portolan 0.1.0

package/src/er/layout.test.ts

@@ -0,0 +1,115 @@
+// Layout, on the two catalogs built to break it.
+//
+// elk itself is not under test here. What is: that the graph handed to it says
+// what we mean — roots first, one constraint per relationship, no self-edges —
+// and that it survives an estate too big to draw and a schema shaped wrong.
+
+import { describe, expect, it } from "vitest";
+import { buildIndex, validateCatalog } from "../catalog";
+import { pathologicalCatalog, wideCatalog } from "../lib/scenarios";
+import { erSpec } from "./spec";
+import { layoutEr, layoutInput } from "./layout";
+
+describe("layoutInput", () => {
+  const bad = pathologicalCatalog();
+  const index = buildIndex(validateCatalog(bad));
+  const store = (bad.stores ?? [])[0];
+  if (!store) throw new Error("scenario has no store");
+  const spec = erSpec(index, store, { mode: "keys" });
+  const input = layoutInput(spec);
+
+  it("reverses every edge, so the table pointed AT is laid out first", () => {
+    // The drawn edge runs child → parent. Laid out that way, the aggregate
+    // root ends up at the far right, which is the opposite of how a schema is
+    // read.
+    const drawn = spec.edges.find(
+      (e) => e.from === "edge.core.pg.a" && e.to === "edge.core.pg.b",
+    );
+    expect(drawn).toBeDefined();
+    expect(
+      input.edges.some(
+        (e) => e.source === "edge.core.pg.b" && e.target === "edge.core.pg.a",
+      ),
+    ).toBe(true);
+  });
+
+  it("drops a self-reference, which constrains nothing", () => {
+    expect(
+      input.edges.some((e) => e.source === e.target),
+    ).toBe(false);
+  });
+
+  it("keeps every table as a node, self-referencing or not", () => {
+    expect(input.nodes.map((n) => n.id).sort()).toEqual(
+      spec.nodes.map((n) => n.id).sort(),
+    );
+  });
+
+  it("collapses two keys between the same pair into one constraint", () => {
+    const pairs = input.edges.map((e) => `${e.source}->${e.target}`);
+    expect(new Set(pairs).size).toBe(pairs.length);
+  });
+});
+
+describe("layoutEr", () => {
+  it("places every table in the pathological store, cycle and all", async () => {
+    const bad = pathologicalCatalog();
+    const index = buildIndex(validateCatalog(bad));
+    const store = (bad.stores ?? [])[0];
+    if (!store) throw new Error("scenario has no store");
+    const spec = erSpec(index, store, { mode: "all" });
+
+    const { positions } = await layoutEr(spec);
+    for (const node of spec.nodes) {
+      expect(positions[node.id]).toBeDefined();
+    }
+  });
+
+  it("puts a chain's first table left of its last", async () => {
+    const wide = wideCatalog();
+    const index = buildIndex(validateCatalog(wide));
+    const store = (wide.stores ?? [])[0];
+    if (!store) throw new Error("scenario has no store");
+    const spec = erSpec(index, store, { mode: "keys" });
+
+    const { positions } = await layoutEr(spec);
+    const first = positions[`${store.id}.t0`];
+    const last = positions[`${store.id}.t5`];
+    expect(first).toBeDefined();
+    expect(last).toBeDefined();
+    expect(first?.x ?? 0).toBeLessThan(last?.x ?? 0);
+  });
+
+  it("answers for an empty store without asking elk anything", async () => {
+    const result = await layoutEr({ nodes: [], edges: [] });
+    expect(result).toEqual({ positions: {}, width: 0, height: 0 });
+  });
+});
+
+describe("the wide estate", () => {
+  const wide = wideCatalog();
+
+  it("validates, which is the first thing a scenario has to do", () => {
+    expect(() => validateCatalog(wide)).not.toThrow();
+  });
+
+  it("is the size it claims to be", () => {
+    expect(wide.stores).toHaveLength(40);
+    const tables = (wide.stores ?? []).reduce(
+      (n, s) => n + s.tables.length,
+      0,
+    );
+    expect(tables).toBeGreaterThanOrEqual(200);
+  });
+
+  it("lays out one of its stores", async () => {
+    const index = buildIndex(validateCatalog(wide));
+    const store = (wide.stores ?? [])[0];
+    if (!store) throw new Error("scenario has no store");
+    const { positions, width } = await layoutEr(
+      erSpec(index, store, { mode: "all" }),
+    );
+    expect(Object.keys(positions)).toHaveLength(store.tables.length);
+    expect(width).toBeGreaterThan(0);
+  });
+});

package/src/er/layout.ts

@@ -0,0 +1,77 @@
+// Where the cards go.
+//
+// One decision worth spelling out: the FK edges handed to elk run the OPPOSITE
+// way from the edges drawn. A foreign key points from the child to the parent,
+// so a layered pass over the real direction puts the aggregate root on the
+// right, at the end of every arrow. Readers do not read a schema that way —
+// they start at the root and follow what hangs off it — so the layout is fed
+// parent → child and the canvas draws child → parent over the top of it.
+//
+// Lineage is fed exactly as it is drawn. It already points the way a reader
+// reads: source on the left, the view computed from it on the right. Reversing
+// it too would put every view before the tables it reads, which is the one
+// arrangement that makes a lineage picture unreadable.
+
+import { layoutWithElk } from "../graph/elk";
+import type { ErSpec } from "./spec";
+
+export interface ErLayout {
+  positions: Record<string, { x: number; y: number }>;
+  width: number;
+  height: number;
+}
+
+export interface ErLayoutInput {
+  nodes: { id: string; width: number; height: number }[];
+  edges: { id: string; source: string; target: string }[];
+}
+
+/**
+ * The layout graph: real nodes, reversed edges, and no duplicate pair. Two
+ * foreign keys between the same two tables are one constraint as far as
+ * placement is concerned, and feeding both makes elk pull them closer than a
+ * single relationship warrants.
+ */
+export function layoutInput(spec: ErSpec): ErLayoutInput {
+  const seen = new Set<string>();
+  const edges: ErLayoutInput["edges"] = [];
+  for (const edge of spec.edges) {
+    // A self-reference constrains nothing and elk lays it out as a cycle of
+    // one; the canvas still draws it.
+    if (edge.from === edge.to) continue;
+    const source = edge.kind === "fk" ? edge.to : edge.from;
+    const target = edge.kind === "fk" ? edge.from : edge.to;
+    const pair = `${source}->${target}`;
+    if (seen.has(pair)) continue;
+    seen.add(pair);
+    edges.push({ id: pair, source, target });
+  }
+
+  return {
+    nodes: spec.nodes.map((n) => ({
+      id: n.id,
+      width: n.width,
+      height: n.height,
+    })),
+    edges,
+  };
+}
+
+/** Lays a spec out left to right, roots first. Falls back to a column on failure. */
+export async function layoutEr(spec: ErSpec): Promise<ErLayout> {
+  const input = layoutInput(spec);
+  if (input.nodes.length === 0) {
+    return { positions: {}, width: 0, height: 0 };
+  }
+
+  const { positions, width, height } = await layoutWithElk({
+    ...input,
+    direction: "RIGHT",
+    // Wider than the graph views' default. A table card is 208px and an edge
+    // between two of them carries "on delete cascade" often enough that a
+    // narrow gap leaves the label sitting on top of the line it describes.
+    layerSpacing: 170,
+    nodeSpacing: 28,
+  });
+  return { positions, width, height };
+}

package/src/er/lineage.test.ts

@@ -0,0 +1,140 @@
+// Walking the lineage graph: both directions, and no walk that never ends.
+
+import { describe, expect, it } from "vitest";
+import { rawCatalog } from "../test-catalog";
+import { buildIndex, validateCatalog } from "../catalog";
+import type { Catalog } from "../catalog";
+import {
+  downstreamOf,
+  isIsolated,
+  lineageChain,
+  lineageEdgeId,
+  parseLineageEdgeId,
+  upstreamOf,
+} from "./lineage";
+import type { LineageMaps } from "./lineage";
+
+/** A graph written the way a catalog declares it: derived end names its sources. */
+function maps(declared: Record<string, string[]>): LineageMaps {
+  const from = new Map<string, string[]>();
+  const into = new Map<string, string[]>();
+  for (const [target, sources] of Object.entries(declared)) {
+    from.set(target, sources);
+    for (const source of sources) {
+      const list = into.get(source) ?? [];
+      list.push(target);
+      into.set(source, list);
+    }
+  }
+  return { from, into };
+}
+
+describe("edge ids", () => {
+  it("round-trips", () => {
+    const id = lineageEdgeId("db.t.a", "db.v.b");
+    expect(id).toBe("db.t.a~>db.v.b");
+    expect(parseLineageEdgeId(id)).toEqual({
+      source: "db.t.a",
+      target: "db.v.b",
+    });
+  });
+
+  it("is not fooled by something that is not an edge id", () => {
+    expect(parseLineageEdgeId("db.t.a")).toBeNull();
+    expect(parseLineageEdgeId("~>db.t.a")).toBeNull();
+  });
+});
+
+describe("walking", () => {
+  // t.a -> v.b -> w.c, with v.b also feeding w.d.
+  const graph = maps({
+    "db.v.b": ["db.t.a"],
+    "db.w.c": ["db.v.b"],
+    "db.w.d": ["db.v.b"],
+  });
+
+  it("follows sources to the far end", () => {
+    expect([...upstreamOf(graph, "db.w.c")].sort()).toEqual([
+      "db.t.a",
+      "db.v.b",
+    ]);
+  });
+
+  it("follows readers to the far end", () => {
+    expect([...downstreamOf(graph, "db.t.a")].sort()).toEqual([
+      "db.v.b",
+      "db.w.c",
+      "db.w.d",
+    ]);
+  });
+
+  it("says nothing about a column nobody copies", () => {
+    expect(upstreamOf(graph, "db.t.a").size).toBe(0);
+    expect(downstreamOf(graph, "db.w.c").size).toBe(0);
+    expect(isIsolated(graph, "db.z.x")).toBe(true);
+    expect(isIsolated(graph, "db.t.a")).toBe(false);
+  });
+
+  it("lights the whole chain from anywhere on it, itself included", () => {
+    const chain = lineageChain(graph, "db.v.b");
+    expect([...chain.columns].sort()).toEqual([
+      "db.t.a",
+      "db.v.b",
+      "db.w.c",
+      "db.w.d",
+    ]);
+    expect([...chain.edges].sort()).toEqual([
+      "db.t.a~>db.v.b",
+      "db.v.b~>db.w.c",
+      "db.v.b~>db.w.d",
+    ]);
+  });
+
+  it("terminates on a cycle", () => {
+    // A catalog mid-migration is allowed to claim a view feeds its own source.
+    const cyclic = maps({ "db.v.b": ["db.t.a"], "db.t.a": ["db.v.b"] });
+    const chain = lineageChain(cyclic, "db.t.a");
+    expect([...chain.columns].sort()).toEqual(["db.t.a", "db.v.b"]);
+    expect(chain.edges.size).toBe(2);
+  });
+});
+
+describe("the catalog's own graph", () => {
+  const catalog = validateCatalog(
+    JSON.parse(JSON.stringify(rawCatalog)) as unknown as Catalog,
+  );
+  const index = buildIndex(catalog);
+  const graph: LineageMaps = {
+    from: index.lineageFrom,
+    into: index.lineageInto,
+  };
+
+  it("has lineage to walk at all", () => {
+    expect(index.lineageFrom.size).toBeGreaterThan(0);
+  });
+
+  it("only ever names columns the catalog has", () => {
+    for (const [target, sources] of index.lineageFrom) {
+      expect(
+        index.columnById.has(target) || index.viewColumnById.has(target),
+        target,
+      ).toBe(true);
+      for (const source of sources) {
+        expect(
+          index.columnById.has(source) || index.viewColumnById.has(source),
+          source,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it("reaches a source table from a view column", () => {
+    const [first] = [...index.viewColumnById.keys()].filter(
+      (id) => (index.lineageFrom.get(id)?.length ?? 0) > 0,
+    );
+    expect(first).toBeDefined();
+    const chain = lineageChain(graph, first as string);
+    expect(chain.columns.size).toBeGreaterThan(1);
+    expect(chain.edges.size).toBeGreaterThan(0);
+  });
+});

package/src/er/lineage.ts

@@ -0,0 +1,107 @@
+// Where a value came from, and who reads it.
+//
+// Foreign keys are a picture of the schema at rest: this row points at that
+// one. Lineage is a picture of the schema in motion — a column of a view, of a
+// projection, of an outbox is a copy of a column somewhere else, and the only
+// question worth asking of it is which one, and what else was copied from the
+// same place.
+//
+// Pure, and deliberately ignorant of the catalog: two maps in, ids out. The
+// index builds the maps once (catalog.ts), the canvas walks them on hover.
+
+/** The lineage graph, in both directions. Keys and values are column ids. */
+export interface LineageMaps {
+  /** column -> the columns it is computed from */
+  from: ReadonlyMap<string, readonly string[]>;
+  /** column -> the columns computed from it */
+  into: ReadonlyMap<string, readonly string[]>;
+}
+
+/**
+ * One lineage edge's id, source first. The canvas draws edges data-first —
+ * left to right, the way it flows — so the id reads the same way.
+ */
+export function lineageEdgeId(source: string, target: string): string {
+  return `${source}~>${target}`;
+}
+
+/** Splits an edge id back into its two ends, or null when it is not one. */
+export function parseLineageEdgeId(
+  id: string,
+): { source: string; target: string } | null {
+  const at = id.indexOf("~>");
+  if (at <= 0) return null;
+  return { source: id.slice(0, at), target: id.slice(at + 2) };
+}
+
+/**
+ * Walks one direction to exhaustion. Every step is guarded by `seen`, so a
+ * catalog that says a view feeds the table it reads — which a mid-migration
+ * catalog is allowed to say — is a cycle that terminates rather than a hang.
+ */
+function walk(
+  edges: ReadonlyMap<string, readonly string[]>,
+  start: string,
+  onEdge: (a: string, b: string) => void,
+): Set<string> {
+  const seen = new Set<string>();
+  const queue = [start];
+  while (queue.length > 0) {
+    const current = queue.shift() as string;
+    for (const next of edges.get(current) ?? []) {
+      onEdge(current, next);
+      if (seen.has(next)) continue;
+      seen.add(next);
+      queue.push(next);
+    }
+  }
+  return seen;
+}
+
+/** Every column this one is computed from, however many hops away. */
+export function upstreamOf(maps: LineageMaps, id: string): Set<string> {
+  return walk(maps.from, id, () => {});
+}
+
+/** Every column computed from this one, however many hops away. */
+export function downstreamOf(maps: LineageMaps, id: string): Set<string> {
+  return walk(maps.into, id, () => {});
+}
+
+/**
+ * The whole chain through one column: everything it came from, everything read
+ * from it, and the edges joining them.
+ *
+ * Both directions, because a reader hovering a column is asking one question
+ * with two halves — "if this changes, what breaks, and if this is wrong, where
+ * did it go wrong". The column itself is in `columns`, so the caller can light
+ * the chain without special-casing where the pointer is.
+ */
+export interface LineageChain {
+  columns: Set<string>;
+  edges: Set<string>;
+}
+
+export function lineageChain(maps: LineageMaps, id: string): LineageChain {
+  const columns = new Set<string>([id]);
+  const edges = new Set<string>();
+
+  for (const found of walk(maps.from, id, (target, source) =>
+    edges.add(lineageEdgeId(source, target)),
+  )) {
+    columns.add(found);
+  }
+  for (const found of walk(maps.into, id, (source, target) =>
+    edges.add(lineageEdgeId(source, target)),
+  )) {
+    columns.add(found);
+  }
+
+  return { columns, edges };
+}
+
+/** True when nothing in the catalog is derived from this column or feeds it. */
+export function isIsolated(maps: LineageMaps, id: string): boolean {
+  return (maps.from.get(id)?.length ?? 0) === 0 &&
+    (maps.into.get(id)?.length ?? 0) === 0;
+}

package/src/er/markers.tsx

@@ -0,0 +1,79 @@
+// Crow's-foot markers, defined once per canvas.
+//
+// The notation is the point: a foreign key is a MANY-to-one relationship, and
+// an arrowhead says only "points at". The fan sits on the table holding the
+// key, the bar on the table it points to, so the cardinality is readable
+// without a legend.
+//
+// Both take their colour from the edge through `context-stroke`, so a
+// highlighted edge highlights its ends with it rather than needing a second
+// pair of markers.
+
+export const MARKER_MANY = "er-many";
+export const MARKER_ONE = "er-one";
+/**
+ * Lineage is not a cardinality, so it gets neither end of the crow's foot: a
+ * plain arrow, pointing the way the data travels. A reader who has learned
+ * that a fan means "many" is not asked to unlearn it here.
+ */
+export const MARKER_FLOW = "er-flow";
+
+export function ErMarkers() {
+  return (
+    <svg
+      aria-hidden
+      width="0"
+      height="0"
+      style={{ position: "absolute", pointerEvents: "none" }}
+    >
+      <defs>
+        <marker
+          id={MARKER_MANY}
+          viewBox="0 0 12 12"
+          markerWidth="12"
+          markerHeight="12"
+          refX="0"
+          refY="6"
+          orient="auto"
+          markerUnits="userSpaceOnUse"
+        >
+          <path
+            d="M0 1 L11 6 M0 6 L11 6 M0 11 L11 6"
+            fill="none"
+            stroke="context-stroke"
+            strokeWidth="1"
+          />
+        </marker>
+        <marker
+          id={MARKER_FLOW}
+          viewBox="0 0 12 12"
+          markerWidth="9"
+          markerHeight="9"
+          refX="9"
+          refY="6"
+          orient="auto"
+          markerUnits="userSpaceOnUse"
+        >
+          <path d="M1 2 L9 6 L1 10 Z" fill="context-stroke" stroke="none" />
+        </marker>
+        <marker
+          id={MARKER_ONE}
+          viewBox="0 0 12 12"
+          markerWidth="12"
+          markerHeight="12"
+          refX="12"
+          refY="6"
+          orient="auto"
+          markerUnits="userSpaceOnUse"
+        >
+          <path
+            d="M7 2 L7 10"
+            fill="none"
+            stroke="context-stroke"
+            strokeWidth="1.2"
+          />
+        </marker>
+      </defs>
+    </svg>
+  );
+}