refactor(graph): migrate Dependencies & Diagram to nx.MultiDiGraph (#1492)

[dimitri-yatsenko]

Resolves #1492.

Migrates Dependencies and Diagram from nx.DiGraph to nx.MultiDiGraph, retiring the integer "alias node" workaround for renamed / multiple foreign keys between the same pair of tables. A renamed FK is now a first-class parallel edge — no synthetic intermediate node.

Why

A plain DiGraph allows one edge per ordered node pair, so a renamed FK was split into parent → "N" → child through an integer alias node, and ~14 .isdigit() special-cases across diagram.py (plus 5 in table.py) existed only to see through those nodes. MultiDiGraph represents parallel edges natively, so the whole workaround is removed — it was a historical design choice, not a NetworkX limitation.

Edge identity

Each edge is keyed by the FK's child-side attribute tuple (in declaration order), e.g. ("spouse1",) vs ("spouse2",). This key is:

• unique among parallel edges between a pair — every FK to a given parent references the parent's primary key, so parallel FKs differ only in their referencing columns;
• schema-derived — no DB-internal constraint names;
• stable & meaningful — so graph merges are idempotent by construction: Diagram + Diagram re-adds a shared FK under the same key (overwrite, not duplicate). No defensive dedup is needed at the call sites.

What changed

• Dependencies/Diagram subclass nx.MultiDiGraph; load() adds one keyed edge per FK; topo_sort drops its alias-collapse pass; cascade()/trace() rebuild via MultiDiGraph.
• Both propagation walkers merged their alias/direct branches into one loop over parallel edges; _find_real_edge_props → _edge_props (direct lookup).
• dependencies.parents()/children() return a parallel-safe list[(node, props)] (was a name-keyed dict that collapsed multiple FKs from the same parent); Table.parents/children/descendants/ancestors/parts drop the .isdigit() handling.
• Rendering: a renamed FK draws as an #FF8800 edge with the column renames in a hover tooltip (dot/SVG) and a linkStyle recolor (mermaid), instead of the orange alias-node dot. The orange color is layered on top of the existing line semantics — solid=primary / dashed=secondary, thick=1:1 / thin=multi are all preserved. _AliasNode tier removed.
• _apply_collapse keeps parallel edges between two expanded tables (by key) while merging edges into a collapsed schema node to a single arrow.

Verification

Full tests/ suite under the pixi test env (MySQL 8.0 + PostgreSQL 15 via testcontainers):

• Green baseline (95 passed) on the graph/cascade/trace/FK suite before any change, reproduced after the migration — behavior-identical.
• Renamed-FK behavior green across all three style cases (solid-thick, solid-thin, dashed-thin — all orange): test_aliased_fk, test_trace_renamed_fk, test_cascade_delete_with_renamed_attrs, test_cascade_part_of_part_renamed_fk, test_upward_u3_nonprimary_master_fk; render smoke tests (test_repr_svg, test_make_image).
• Full suite: 949 passed, 10 skipped, 0 failures (both backends).

Notes

• Milestone v2.3.2. Paired docs update: docs(diagram): renamed FKs as orange edges [blocked on v2.3.2 / dj-python#1508] datajoint-docs#215 (renamed-FK notation), gated on this shipping.

[dimitri-yatsenko]

Paired docs PR: datajoint/datajoint-docs#215 — updates the diagram-notation docs (renamed FKs render as orange edges with a rename tooltip instead of alias-node dots) and adds a renamed-primary example showing the line-style semantics are retained.

The docs PR re-executed its notebooks against this branch, so it is gated on this shipping in v2.3.2 and must not merge until the release.