quickdbd-cli 0.1.0__py3-none-any.whl

quickdbd_cli/jsrt.py

@@ -0,0 +1,77 @@
+"""Embedded JavaScript runtime (V8 via mini-racer) for ELK layout and render.js.
+
+mini-racer's built-in setTimeout does not work reliably, so a synchronous timer queue is
+installed instead and drained from Python; ELK only uses setTimeout(0) to fake a worker.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+from functools import cache
+from importlib import resources
+
+from py_mini_racer import MiniRacer
+
+_SHIM = """
+globalThis.global = globalThis;
+var __q = [];
+globalThis.setTimeout = function (f) { __q.push(f); return __q.length; };
+globalThis.clearTimeout = function () {};
+function __drain() { var n = 0; while (__q.length) { __q.shift()(); n++; } return n; }
+var __res = null, __err = null;
+"""
+
+
+def _asset(name: str) -> str:
+    return resources.files("quickdbd_cli").joinpath(f"assets/{name}").read_text(encoding="utf-8")
+
+
+class _Runtime:
+    def __init__(self) -> None:
+        self.ctx = MiniRacer()
+        self.ctx.eval(_SHIM)
+        self.loaded: set[str] = set()
+
+    def load(self, name: str) -> None:
+        if name not in self.loaded:
+            self.ctx.eval(_asset(name))
+            self.loaded.add(name)
+
+    def call(self, fn: str, *args) -> object:
+        """Call a global JS function with JSON-serialisable args; returns the JSON-decoded result."""
+        argv = ", ".join(f"JSON.parse({json.dumps(json.dumps(a))})" for a in args)
+        return json.loads(self.ctx.eval(f"JSON.stringify({fn}({argv}))"))
+
+    def call_async(self, expr_fn: str, *args) -> object:
+        """Call a JS function returning a Promise, draining the timer queue until it settles."""
+        argv = ", ".join(f"JSON.parse({json.dumps(json.dumps(a))})" for a in args)
+        self.ctx.eval("__res = null; __err = null;")
+        self.ctx.eval(
+            f"Promise.resolve({expr_fn}({argv})).then("
+            "function (r) { __res = JSON.stringify(r); }, function (e) { __err = String(e && e.stack || e); });"
+        )
+        for _ in range(10000):
+            self.ctx.eval("__drain()")
+            if self.ctx.eval("__res !== null || __err !== null"):
+                break
+        err = self.ctx.eval("__err")
+        if err:
+            raise RuntimeError(f"JavaScript error: {err}")
+        res = self.ctx.eval("__res")
+        if res is None:
+            raise RuntimeError("JavaScript promise did not settle")
+        return json.loads(res)
+
+    def close(self) -> None:
+        try:
+            self.ctx.close()
+        except Exception:
+            pass
+
+
+@cache
+def runtime() -> _Runtime:
+    rt = _Runtime()
+    atexit.register(rt.close)
+    return rt

quickdbd_cli/layout.py

@@ -0,0 +1,207 @@
+"""Table positions: sidecar file, QuickDBD [layout] import, ELK auto-layout, new-table placement."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from .jsrt import runtime
+
+_GLUE = """
+function qdbdElkLayout(graph) {
+  return new ELK().layout(graph).then(function (r) {
+    var out = {};
+    (r.children || []).forEach(function (c) { out[c.id] = [Math.round(c.x), Math.round(c.y)]; });
+    return out;
+  });
+}
+"""
+
+# Stress layout keeps related tables close together (short relationship lines), then
+# ELK's overlap removal pushes tables apart. Layered layouts were tried and produced very
+# long lines on 200-table schemas.
+STRESS_OPTIONS = {
+    "elk.algorithm": "stress",
+    "elk.stress.desiredEdgeLength": "250",
+    "elk.randomSeed": "1",
+}
+OVERLAP_OPTIONS = {
+    "elk.algorithm": "sporeOverlap",
+    "elk.spacing.nodeNode": "40",
+    "elk.randomSeed": "1",
+}
+
+MARGIN = 30
+Positions = dict[str, tuple[int, int]]
+
+
+def elk_layout(tables: list[dict], rels: list[dict]) -> Positions:
+    """Lay out ``tables`` (model_json table dicts) with ELK; only rels between them are used."""
+    if not tables:
+        return {}
+    ids = {t["id"] for t in tables}
+    rt = runtime()
+    rt.load("elk.bundled.js")
+    if "glue" not in rt.loaded:
+        rt.ctx.eval(_GLUE)
+        rt.loaded.add("glue")
+    edges = []
+    seen = set()
+    for r in rels:
+        a, b = r["a"]["t"], r["b"]["t"]
+        # Edges point from the referencing (many/FK) side to the referenced side.
+        src, dst = (a, b) if r["a"]["card"] in ("many", "zeroMany") or r["b"]["card"] == "one" else (b, a)
+        if src in ids and dst in ids and src != dst and (src, dst) not in seen:
+            seen.add((src, dst))
+            edges.append({"id": f"e{len(edges)}", "sources": [src], "targets": [dst]})
+    graph = {
+        "id": "root",
+        "layoutOptions": STRESS_OPTIONS,
+        "children": [{"id": t["id"], "width": t["w"], "height": t["h"]} for t in tables],
+        "edges": edges,
+    }
+    first = rt.call_async("qdbdElkLayout", graph)
+    graph = {
+        "id": "root",
+        "layoutOptions": OVERLAP_OPTIONS,
+        "children": [
+            {"id": t["id"], "width": t["w"], "height": t["h"], "x": first[t["id"]][0], "y": first[t["id"]][1]}
+            for t in tables
+        ],
+        "edges": [],
+    }
+    raw = rt.call_async("qdbdElkLayout", graph)
+    min_x = min(v[0] for v in raw.values())
+    min_y = min(v[1] for v in raw.values())
+    return {k: (int(v[0] - min_x), int(v[1] - min_y)) for k, v in raw.items()}
+
+
+def _overlaps(x: float, y: float, w: float, h: float, rects: list[tuple[float, float, float, float]]) -> bool:
+    for rx, ry, rw, rh in rects:
+        if x < rx + rw + MARGIN and rx < x + w + MARGIN and y < ry + rh + MARGIN and ry < y + h + MARGIN:
+            return True
+    return False
+
+
+def _free_spot(cx: float, cy: float, w: float, h: float, rects, step: int = 30) -> tuple[int, int]:
+    """Nearest non-overlapping top-left position to centre (cx, cy), searched in square rings."""
+    x0, y0 = cx - w / 2, cy - h / 2
+    for ring in range(0, 400):
+        cands = []
+        for dx in range(-ring, ring + 1):
+            for dy in range(-ring, ring + 1):
+                if max(abs(dx), abs(dy)) == ring:
+                    cands.append((dx * dx + dy * dy, dx, dy))
+        for _, dx, dy in sorted(cands):
+            x, y = x0 + dx * step, y0 + dy * step
+            if not _overlaps(x, y, w, h, rects):
+                return int(round(x)), int(round(y))
+    return int(round(x0)), int(round(y0))
+
+
+def place_missing(tables: list[dict], rels: list[dict], positions: Positions) -> Positions:
+    """Positions for every table. Existing positions never move.
+
+    Tables with already-placed neighbours go into the nearest free space around those neighbours;
+    the rest are laid out together with ELK and put below the existing diagram.
+    """
+    by_id = {t["id"]: t for t in tables}
+    pos: Positions = {k: v for k, v in positions.items() if k in by_id}
+    missing = [t["id"] for t in tables if t["id"] not in pos]
+    if not missing:
+        return pos
+    if not pos:
+        return elk_layout(tables, rels)
+
+    neighbours: dict[str, list[str]] = {t["id"]: [] for t in tables}
+    for r in rels:
+        a, b = r["a"]["t"], r["b"]["t"]
+        if a != b and a in neighbours and b in neighbours:
+            neighbours[a].append(b)
+            neighbours[b].append(a)
+    order = {tid: i for i, tid in enumerate(t["id"] for t in tables)}
+    rects = [(x, y, by_id[k]["w"], by_id[k]["h"]) for k, (x, y) in pos.items()]
+
+    pending = set(missing)
+    while True:
+        ready = [(sum(1 for n in neighbours[t] if n in pos), t) for t in pending]
+        ready = [(n, t) for n, t in ready if n > 0]
+        if not ready:
+            break
+        ready.sort(key=lambda nt: (-nt[0], order[nt[1]]))
+        tid = ready[0][1]
+        t = by_id[tid]
+        placed = [n for n in neighbours[tid] if n in pos]
+        cx = sum(pos[n][0] + by_id[n]["w"] / 2 for n in placed) / len(placed)
+        cy = sum(pos[n][1] + by_id[n]["h"] / 2 for n in placed) / len(placed)
+        x, y = _free_spot(cx, cy, t["w"], t["h"], rects)
+        pos[tid] = (x, y)
+        rects.append((x, y, t["w"], t["h"]))
+        pending.discard(tid)
+
+    if pending:
+        rest = [by_id[t] for t in missing if t in pending]
+        block = elk_layout(rest, rels)
+        min_x = min(r[0] for r in rects)
+        max_y = max(r[1] + r[3] for r in rects)
+        bx = min(v[0] for v in block.values())
+        by = min(v[1] for v in block.values())
+        for tid, (x, y) in block.items():
+            pos[tid] = (x - bx + min_x, y - by + max_y + 120)
+    return pos
+
+
+# --------------------------------------------------------------------------- sidecar
+
+
+def default_sidecar(files: list[Path], inputs: list[Path]) -> Path:
+    if len(inputs) == 1 and inputs[0].is_file():
+        f = inputs[0]
+        return f.with_name(f.stem + ".layout.json")
+    if len(inputs) == 1 and inputs[0].is_dir():
+        return inputs[0] / "qdbd.layout.json"
+    common = Path(os.path.commonpath([str(p.resolve().parent) for p in files])) if files else Path.cwd()
+    return common / "qdbd.layout.json"
+
+
+def read_sidecar(path: Path) -> dict[str, tuple[int, int]]:
+    """Returns {table name: (x, y)}."""
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {name: (int(v["x"]), int(v["y"])) for name, v in data.get("tables", {}).items()}
+
+
+def write_sidecar(path: Path, by_name: dict[str, tuple[int, int]]) -> None:
+    data = {
+        "version": 1,
+        "tables": {n: {"x": int(x), "y": int(y)} for n, (x, y) in sorted(by_name.items())},
+    }
+    text = json.dumps(data, indent=2, sort_keys=True) + "\n"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".qdbd-", suffix=".tmp")
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, path)
+
+
+def resolve_positions(
+    model: dict, sidecar: dict[str, tuple[int, int]], qdbd_layout: dict, reset: bool = False
+) -> Positions:
+    """Sidecar (by table name) > QuickDBD [layout] section > auto placement."""
+    tables = model["tables"]
+    pos: Positions = {}
+    if not reset:
+        for t in tables:
+            if t["name"] in sidecar:
+                pos[t["id"]] = sidecar[t["name"]]
+            elif t["id"] in qdbd_layout:
+                x, y = qdbd_layout[t["id"]]
+                pos[t["id"]] = (int(x), int(y))
+    return place_missing(tables, model["rels"], pos)
+
+
+def positions_by_name(model: dict, pos: Positions) -> dict[str, tuple[int, int]]:
+    return {t["name"]: pos[t["id"]] for t in model["tables"] if t["id"] in pos}

quickdbd_cli/measure.py

@@ -0,0 +1,111 @@
+"""Text measurement and the diagram model handed to render.js.
+
+Widths come from a committed per-glyph table for the bundled Inter font
+(see scripts/gen_font_metrics.py), so Python, the browser, and the PNG export agree.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+
+from .model import Column, Schema, Table
+
+STYLE = {
+    "font": "Inter",
+    "headerH": 32,
+    "headerSize": 14,
+    "rowH": 24,
+    "rowSize": 12,
+    "padX": 12,
+    "gap": 20,
+    "keyW": 16,
+    "badgeSize": 9,
+    "badgePad": 4,
+    "badgeGap": 4,
+    "bottomPad": 4,
+    "minW": 120,
+}
+
+
+@cache
+def _metrics() -> dict:
+    return json.loads(resources.files("quickdbd_cli").joinpath("assets/font-metrics.json").read_text())
+
+
+def text_width(text: str, size: float, bold: bool = False) -> float:
+    table = _metrics()["bold" if bold else "regular"]
+    return round(sum(table.get(ch, 0.6) for ch in text) * size, 2)
+
+
+def badges(col: Column) -> list[str]:
+    out = []
+    if col.identity:
+        out.append("auto")
+    if col.unique:
+        out.append("unique")
+    if col.index:
+        out.append("index")
+    if col.nullable:
+        out.append("null")
+    if col.default is not None:
+        out.append(f"={col.default}")
+    return out
+
+
+def _column_json(col: Column) -> dict:
+    s = STYLE
+    bold = col.pk or col.fk
+    name_w = text_width(col.name, s["rowSize"], bold)
+    bs = [{"t": b, "w": round(text_width(b, s["badgeSize"]) + 2 * s["badgePad"], 2)} for b in badges(col)]
+    type_w = text_width(col.type or "", s["rowSize"])
+    return {
+        "id": col.id,
+        "name": col.name,
+        "type": col.type or "",
+        "pk": col.pk,
+        "fk": col.fk,
+        "nullable": col.nullable,
+        "unique": col.unique,
+        "index": col.index,
+        "identity": col.identity,
+        "default": col.default,
+        "nameW": name_w,
+        "typeW": type_w,
+        "badges": bs,
+    }
+
+
+def table_json(table: Table) -> dict:
+    s = STYLE
+    cols = [_column_json(c) for c in table.columns.values() if not c.virtual]
+    w = text_width(table.name, s["headerSize"]) + 2 * s["padX"]
+    for c in cols:
+        row = c["nameW"] + c["typeW"] + 2 * s["padX"] + s["gap"]
+        row += sum(b["w"] + s["badgeGap"] for b in c["badges"])
+        if c["pk"]:
+            row += s["keyW"]
+        w = max(w, row)
+    w = max(round(w), s["minW"])
+    h = s["headerH"] + len(cols) * s["rowH"] + s["bottomPad"]
+    return {"id": table.id, "name": table.name, "aliases": table.aliases, "w": w, "h": h, "cols": cols}
+
+
+def model_json(schema: Schema) -> dict:
+    """Plain-JSON diagram model (no positions)."""
+    rels = []
+    for r in schema.valid_relationships():
+        rels.append(
+            {
+                "a": {"t": r.a.table, "c": r.a.column, "card": r.a.card},
+                "b": {"t": r.b.table, "c": r.b.column, "card": r.b.card},
+            }
+        )
+    return {
+        "style": STYLE,
+        "tables": [table_json(t) for t in schema.tables.values()],
+        "rels": rels,
+        "zoom": schema.zoom,
+        "position": list(schema.position) if schema.position else None,
+    }

quickdbd_cli/model.py

@@ -0,0 +1,107 @@
+"""Data model shared by the parser, layout, and renderers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+VIRTUAL_FIELD = "qdbdvirtualfield"
+
+# Relationship operator -> (cardinality of left member, cardinality of right member)
+REL_TYPES: dict[str, tuple[str, str]] = {
+    "-": ("one", "one"),
+    "-<": ("one", "many"),
+    ">-": ("many", "one"),
+    ">-<": ("many", "many"),
+    "-0": ("one", "zeroOne"),
+    "0-": ("zeroOne", "one"),
+    "0-0": ("zeroOne", "zeroOne"),
+    "-0<": ("one", "zeroMany"),
+    ">0-": ("zeroMany", "one"),
+}
+
+
+@dataclass
+class Diagnostic:
+    path: str
+    line: int
+    message: str
+    severity: str = "error"  # "error" | "warning"
+
+    def format(self) -> str:
+        return f"{self.path}:{self.line}: {self.severity}: {self.message}"
+
+
+@dataclass
+class Column:
+    id: str
+    name: str
+    line: int
+    order: int = 0
+    type: str | None = None
+    pk: bool = False
+    fk: bool = False
+    nullable: bool = False
+    unique: bool = False
+    index: bool = False
+    identity: bool = False
+    default: str | None = None
+    virtual: bool = False
+    comments: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Table:
+    id: str
+    name: str
+    path: str
+    line: int
+    aliases: list[str] = field(default_factory=list)
+    columns: dict[str, Column] = field(default_factory=dict)
+    comments: list[str] = field(default_factory=list)
+
+
+@dataclass
+class End:
+    table: str
+    column: str  # column id, or VIRTUAL_FIELD for a table-level relationship
+    card: str = "one"
+
+
+@dataclass
+class Relationship:
+    a: End
+    b: End
+    path: str
+    line: int
+
+
+@dataclass
+class Schema:
+    tables: dict[str, Table] = field(default_factory=dict)
+    relationships: list[Relationship] = field(default_factory=list)
+    zoom: float | None = None
+    position: tuple[float, float] | None = None
+    layout: dict[str, tuple[float, float]] = field(default_factory=dict)
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    general_comments: list[str] = field(default_factory=list)
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity == "error"]
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        return [d for d in self.diagnostics if d.severity == "warning"]
+
+    def valid_relationships(self) -> list[Relationship]:
+        """Relationships whose both ends resolve to existing tables/columns."""
+        out = []
+        for rel in self.relationships:
+            ok = True
+            for end in (rel.a, rel.b):
+                t = self.tables.get(end.table)
+                if t is None or end.column not in t.columns:
+                    ok = False
+            if ok:
+                out.append(rel)
+        return out