ts-prorm-orm 1.1.0

package/dist/diagrams/dependency-diagram.js

@@ -0,0 +1,432 @@
+"use strict";
+/**
+ * DependencyDiagram — renders a directed dependency graph of models/tables.
+ *
+ * Nodes are models/tables; a directed edge `from → to` means "from depends on
+ * to" (e.g. table `from` holds a foreign key into table `to`). The generator:
+ *
+ *  - Computes a layered / topological layout: each node's layer is the longest
+ *    dependency path to a leaf. Nodes with no dependencies sit in layer 0;
+ *    their dependents fan out into higher layers.
+ *  - Detects cycles (back edges) with a DFS colouring pass and visually flags
+ *    the cyclic edges in red. The layering pass carries its own visited guard
+ *    so a cycle can never send it into an infinite loop.
+ *  - Draws each node as a labelled rounded box sized to its label, with arrows
+ *    between dependent boxes.
+ *
+ * Accent colour (`color`) drives the node fills / arrowheads; the theme
+ * (`light` | `dark`) drives the canvas + text colours. Both genuinely change
+ * real fill/stroke values in the emitted SVG. The viewBox auto-sizes to the
+ * computed layout.
+ *
+ * Usage:
+ *   const d = new DependencyDiagram({ nodes, edges, title: 'Schema deps' });
+ *   const svg = d.generate();
+ *   d.save('./diagrams/deps.svg');
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyDiagram = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const palette_1 = require("./palette");
+const svg_dom_1 = require("./svg-dom");
+// ─── Main class ──────────────────────────────────────────────────────────────
+class DependencyDiagram {
+    constructor(options) {
+        this.opts = {
+            title: options.title ?? 'Dependency Graph',
+            theme: options.theme ?? 'light',
+            color: options.color ?? '',
+            direction: options.direction ?? 'horizontal',
+            nodes: options.nodes ?? [],
+            edges: options.edges ?? [],
+        };
+    }
+    // ── Graph analysis ──────────────────────────────────────────────────────
+    /** Adjacency: node → the nodes it depends on (its outgoing edge targets). */
+    buildAdjacency(names) {
+        const adj = new Map();
+        for (const n of names)
+            adj.set(n, []);
+        for (const e of this.opts.edges) {
+            if (!names.has(e.from) || !names.has(e.to))
+                continue;
+            if (e.from === e.to)
+                continue; // ignore trivial self-loops for layering
+            adj.get(e.from).push(e.to);
+        }
+        return adj;
+    }
+    /**
+     * Assign each node a layer = longest dependency path length (0 for nodes with
+     * no dependencies). Uses memoisation plus an on-stack guard so cyclic edges
+     * are simply skipped and never cause infinite recursion.
+     */
+    computeLayers(names, adj) {
+        const layer = new Map();
+        const onStack = new Set();
+        const visit = (node) => {
+            if (layer.has(node))
+                return layer.get(node);
+            if (onStack.has(node))
+                return 0; // cycle guard — break the recursion
+            onStack.add(node);
+            let best = 0;
+            for (const dep of adj.get(node) ?? []) {
+                best = Math.max(best, visit(dep) + 1);
+            }
+            onStack.delete(node);
+            layer.set(node, best);
+            return best;
+        };
+        for (const n of names)
+            visit(n);
+        return layer;
+    }
+    /**
+     * Detect cyclic edges via DFS colouring. Returns a set of "from→to" keys that
+     * are back edges (participate in a cycle).
+     */
+    detectCyclicEdges(names, adj) {
+        const cyclic = new Set();
+        const WHITE = 0;
+        const GRAY = 1;
+        const BLACK = 2;
+        const color = new Map();
+        for (const n of names)
+            color.set(n, WHITE);
+        const dfs = (node) => {
+            color.set(node, GRAY);
+            for (const dep of adj.get(node) ?? []) {
+                const c = color.get(dep);
+                if (c === GRAY) {
+                    cyclic.add(`${node}${dep}`); // back edge → cycle
+                }
+                else if (c === WHITE) {
+                    dfs(dep);
+                }
+            }
+            color.set(node, BLACK);
+        };
+        for (const n of names)
+            if (color.get(n) === WHITE)
+                dfs(n);
+        return cyclic;
+    }
+    // ── Geometry helpers ─────────────────────────────────────────────────────
+    nodeWidth(name) {
+        return Math.max(DependencyDiagram.MIN_NODE_W, Math.round(name.length * DependencyDiagram.CHAR_W + DependencyDiagram.NODE_PAD_X * 2));
+    }
+    /**
+     * Point on the boundary of a rectangle along the line from the rect centre
+     * toward an external point — used so arrowheads land on the box edge.
+     */
+    edgePoint(node, tx, ty) {
+        const cx = node.x + node.w / 2;
+        const cy = node.y + node.h / 2;
+        let dx = tx - cx;
+        let dy = ty - cy;
+        if (dx === 0 && dy === 0)
+            return { x: cx, y: cy };
+        const halfW = node.w / 2;
+        const halfH = node.h / 2;
+        const scaleX = dx !== 0 ? halfW / Math.abs(dx) : Infinity;
+        const scaleY = dy !== 0 ? halfH / Math.abs(dy) : Infinity;
+        const scale = Math.min(scaleX, scaleY);
+        return { x: cx + dx * scale, y: cy + dy * scale };
+    }
+    // ── Generate full SVG string ─────────────────────────────────────────────
+    generate() {
+        const { title, theme, color, direction } = this.opts;
+        const accent = (0, palette_1.resolveAccent)(color);
+        const palettes = (0, palette_1.rotatedPalettes)(color);
+        const t = (0, palette_1.resolveTheme)(theme);
+        const horizontal = direction !== 'vertical';
+        const PAD = DependencyDiagram.PAD;
+        const TITLE_H = DependencyDiagram.TITLE_H;
+        const NODE_H = DependencyDiagram.NODE_H;
+        const LAYER_GAP = DependencyDiagram.LAYER_GAP;
+        const NODE_GAP = DependencyDiagram.NODE_GAP;
+        const R = DependencyDiagram.R;
+        // De-duplicate nodes by name, preserving first occurrence.
+        const seen = new Set();
+        const nodeDefs = [];
+        for (const n of this.opts.nodes) {
+            if (!n || seen.has(n.name))
+                continue;
+            seen.add(n.name);
+            nodeDefs.push(n);
+        }
+        const names = nodeDefs.map((n) => n.name);
+        const nameSet = new Set(names);
+        const adj = this.buildAdjacency(nameSet);
+        const layerMap = this.computeLayers(names, adj);
+        const cyclicEdges = this.detectCyclicEdges(names, adj);
+        // Group nodes into layers preserving input order for stable slots.
+        const layersArr = [];
+        for (const n of nodeDefs) {
+            const l = layerMap.get(n.name) ?? 0;
+            (layersArr[l] ?? (layersArr[l] = [])).push(n);
+        }
+        for (let i = 0; i < layersArr.length; i++)
+            layersArr[i] ?? (layersArr[i] = []);
+        // Assign a stable palette per group (for node fill tinting).
+        const groupPalette = new Map();
+        let gi = 0;
+        for (const n of nodeDefs) {
+            const g = n.group;
+            if (g && !groupPalette.has(g)) {
+                groupPalette.set(g, palettes[gi % palettes.length]);
+                gi++;
+            }
+        }
+        // ── Compute placements ──────────────────────────────────────────────
+        const placed = new Map();
+        if (horizontal) {
+            // Layers = columns (left→right). Nodes stacked vertically within a column.
+            const layerW = layersArr.map((layer) => layer.reduce((m, n) => Math.max(m, this.nodeWidth(n.name)), DependencyDiagram.MIN_NODE_W));
+            const colX = [];
+            let cursor = PAD;
+            for (let l = 0; l < layersArr.length; l++) {
+                colX[l] = cursor;
+                cursor += layerW[l] + LAYER_GAP;
+            }
+            const contentTop = PAD + TITLE_H;
+            for (let l = 0; l < layersArr.length; l++) {
+                layersArr[l].forEach((n, slot) => {
+                    const w = this.nodeWidth(n.name);
+                    const x = colX[l] + (layerW[l] - w) / 2;
+                    const y = contentTop + slot * (NODE_H + NODE_GAP);
+                    this.place(placed, n, l, slot, x, y, w, NODE_H, accent, groupPalette, t);
+                });
+            }
+        }
+        else {
+            // Layers = rows (top→bottom). Nodes spread horizontally within a row.
+            const colW = names.reduce((m, nm) => Math.max(m, this.nodeWidth(nm)), DependencyDiagram.MIN_NODE_W);
+            const contentLeft = PAD;
+            for (let l = 0; l < layersArr.length; l++) {
+                const y = PAD + TITLE_H + l * (NODE_H + LAYER_GAP);
+                layersArr[l].forEach((n, slot) => {
+                    const w = this.nodeWidth(n.name);
+                    const x = contentLeft + slot * (colW + NODE_GAP) + (colW - w) / 2;
+                    this.place(placed, n, l, slot, x, y, w, NODE_H, accent, groupPalette, t);
+                });
+            }
+        }
+        // ── Auto-size the canvas ────────────────────────────────────────────
+        let maxX = 0;
+        let maxY = 0;
+        for (const p of placed.values()) {
+            maxX = Math.max(maxX, p.x + p.w);
+            maxY = Math.max(maxY, p.y + p.h);
+        }
+        const svgW = Math.round(maxX + PAD);
+        const svgH = Math.round(maxY + PAD);
+        // ── Build the document ──────────────────────────────────────────────
+        const doc = new svg_dom_1.SvgDocument(svgW, svgH);
+        const svg = doc.root;
+        // Background
+        svg.child('rect', { width: svgW, height: svgH, fill: t.canvasBg });
+        // Arrowhead markers (accent + cyclic red).
+        const CYCLE_COLOR = '#DC2626';
+        this.defineArrow(doc, 'depArrow', accent.mid);
+        this.defineArrow(doc, 'depArrowCycle', CYCLE_COLOR);
+        // Title
+        svg
+            .child('text', {
+            x: PAD,
+            y: PAD + 6,
+            'font-family': 'system-ui,-apple-system,sans-serif',
+            'font-size': 22,
+            'font-weight': 800,
+            fill: t.textPrimary,
+        })
+            .text(title);
+        svg
+            .child('text', {
+            x: PAD,
+            y: PAD + 26,
+            'font-family': 'system-ui,sans-serif',
+            'font-size': 11,
+            fill: t.textSecondary,
+        })
+            .text(`${placed.size} node${placed.size !== 1 ? 's' : ''} · ${this.opts.edges.length} edge${this.opts.edges.length !== 1 ? 's' : ''}${cyclicEdges.size ? ` · ${cyclicEdges.size} cyclic` : ''}`);
+        // ── Edges (drawn before nodes so boxes sit on top) ──────────────────
+        const edgeLayer = svg.child('g', { 'stroke-linecap': 'round' });
+        for (const e of this.opts.edges) {
+            const from = placed.get(e.from);
+            const to = placed.get(e.to);
+            if (!from || !to)
+                continue;
+            const isCyclic = cyclicEdges.has(`${e.from}${e.to}`);
+            const isSelf = e.from === e.to;
+            const stroke = isCyclic ? CYCLE_COLOR : accent.mid;
+            const marker = isCyclic ? 'url(#depArrowCycle)' : 'url(#depArrow)';
+            if (isSelf) {
+                // Self-dependency: small loop above the node.
+                const lx = from.x + from.w / 2;
+                const ly = from.y;
+                edgeLayer.child('path', {
+                    d: `M ${lx - 10} ${ly} C ${lx - 26} ${ly - 34}, ${lx + 26} ${ly - 34}, ${lx + 10} ${ly}`,
+                    fill: 'none',
+                    stroke,
+                    'stroke-width': isCyclic ? 2.4 : 1.8,
+                    'stroke-dasharray': isCyclic ? '6 4' : undefined,
+                    'marker-end': marker,
+                });
+                continue;
+            }
+            const toCx = to.x + to.w / 2;
+            const toCy = to.y + to.h / 2;
+            const fromCx = from.x + from.w / 2;
+            const fromCy = from.y + from.h / 2;
+            const start = this.edgePoint(from, toCx, toCy);
+            const end = this.edgePoint(to, fromCx, fromCy);
+            edgeLayer.child('line', {
+                x1: start.x,
+                y1: start.y,
+                x2: end.x,
+                y2: end.y,
+                stroke,
+                'stroke-width': isCyclic ? 2.4 : 1.7,
+                'stroke-dasharray': isCyclic ? '6 4' : undefined,
+                'marker-end': marker,
+            });
+            if (e.label) {
+                svg
+                    .child('text', {
+                    x: (start.x + end.x) / 2,
+                    y: (start.y + end.y) / 2 - 4,
+                    'font-family': "'SF Mono',monospace",
+                    'font-size': 9,
+                    fill: isCyclic ? CYCLE_COLOR : t.textSecondary,
+                    'text-anchor': 'middle',
+                })
+                    .text(e.label);
+            }
+        }
+        // ── Nodes ───────────────────────────────────────────────────────────
+        for (const n of nodeDefs) {
+            const p = placed.get(n.name);
+            if (!p)
+                continue;
+            const g = svg.child('g');
+            g.child('rect', {
+                x: p.x,
+                y: p.y,
+                width: p.w,
+                height: p.h,
+                rx: R,
+                fill: p.fill,
+                stroke: p.stroke,
+                'stroke-width': 2,
+            });
+            g.child('text', {
+                x: p.x + p.w / 2,
+                y: p.y + p.h / 2 + 5,
+                'font-family': "'SF Mono','Fira Code',monospace",
+                'font-size': 14,
+                'font-weight': 700,
+                fill: p.text,
+                'text-anchor': 'middle',
+            }).text(n.name);
+            // Layer badge on the box shoulder.
+            g.child('text', {
+                x: p.x + 8,
+                y: p.y + 13,
+                'font-family': 'system-ui,sans-serif',
+                'font-size': 9,
+                'font-weight': 700,
+                fill: p.text,
+                opacity: 0.55,
+            }).text(`L${p.layer}`);
+        }
+        return doc.toString('Generated by ts-prorm-orm DependencyDiagram');
+    }
+    // ── place() records a node's geometry + resolved colours ─────────────────
+    place(placed, n, layer, slot, x, y, w, h, accent, groupPalette, t) {
+        const pal = (n.group && groupPalette.get(n.group)) || accent;
+        placed.set(n.name, {
+            name: n.name,
+            group: n.group,
+            layer,
+            slot,
+            x,
+            y,
+            w,
+            h,
+            fill: pal.light,
+            stroke: pal.mid,
+            text: pal.text,
+        });
+    }
+    // ── Arrowhead marker in <defs> ───────────────────────────────────────────
+    defineArrow(doc, id, color) {
+        const marker = doc.defs().child('marker', {
+            id,
+            viewBox: '0 0 10 10',
+            refX: 9,
+            refY: 5,
+            markerWidth: 7,
+            markerHeight: 7,
+            orient: 'auto-start-reverse',
+        });
+        marker.child('path', { d: 'M 0 0 L 10 5 L 0 10 z', fill: color });
+    }
+    /**
+     * Write the SVG to a file, creating parent directories as needed.
+     */
+    save(outputPath) {
+        const resolved = path.resolve(outputPath);
+        const dir = path.dirname(resolved);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(resolved, this.generate(), 'utf-8');
+        return resolved;
+    }
+}
+exports.DependencyDiagram = DependencyDiagram;
+// Layout constants (px)
+DependencyDiagram.PAD = 40;
+DependencyDiagram.TITLE_H = 48;
+DependencyDiagram.NODE_H = 40;
+DependencyDiagram.CHAR_W = 8.4;
+DependencyDiagram.NODE_PAD_X = 22;
+DependencyDiagram.MIN_NODE_W = 72;
+DependencyDiagram.LAYER_GAP = 90; // gap between layer columns/rows
+DependencyDiagram.NODE_GAP = 26; // gap between nodes in a layer
+DependencyDiagram.R = 9;