quickdbd-cli 0.1.4__tar.gz → 0.1.5__tar.gz

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/.gitignore

@@ -220,3 +220,4 @@ __marimo__/
 .streamlit/secrets.toml
 .venv/
 .superpowers/
+site/

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.4
+Version: 0.1.5
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://github.com/MarkPhamm/quickdbd-cli
 Author: Minh (Mark) Pham
@@ -21,6 +21,9 @@ Provides-Extra: dev
 Requires-Dist: fonttools>=4.50; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # quickdbd-cli (`qdbd`)
@@ -44,7 +47,7 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
-**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
 
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
@@ -60,6 +63,8 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
   - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -129,11 +134,12 @@ The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -177,7 +183,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.4
+      - uses: MarkPhamm/quickdbd-cli@v0.1.5
         with:
           path: erd/                 # schema file(s) or folder(s)
           output: site/index.html
@@ -201,7 +207,7 @@ Outputs are `html`, `changed` and `diff-file`.
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.4
+    rev: v0.1.5
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$   # point at your schema files

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/README.md

@@ -19,7 +19,7 @@ pipx install quickdbd-cli        # or: uvx --from quickdbd-cli qdbd ...
 qdbd build schema.txt -o schema.html
 ```
 
-**Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/
+**Docs:** https://markphamm.github.io/quickdbd-cli/ · **Live demo (200 tables):** https://markphamm.github.io/quickdbd-cli/demo/
 
 Not affiliated with QuickDBD. It reads the same text syntax, so schemas move freely between the two.
 
@@ -35,6 +35,8 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - hover a column to highlight its relationship
   - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons, and **draw.io**: an editable diagrams.net file using draw.io's ER table shapes and crow's-foot arrows
+  - **Path finder:** in a table's detail panel, type another table to see the shortest join path, highlighted on the canvas, with a ready-to-paste SQL `JOIN` (also `qdbd path erd/ --from payments --to customers`)
+  - **Regions:** a shaded, labelled area per file or dbt folder (toolbar toggle). `--by-group` on `build` / `export` / `layout` arranges tables so each folder sits together
   - shareable links: the URL keeps the filter, selected table, collapse mode and zoom; **Link** copies it
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -104,11 +106,12 @@ The selector `diff:modified` (or `diff:added` / `diff:changed`) works like dbt's
 
 ```bash
 qdbd check  PATH... [--strict]                 # validate; "No errors found. Good job!"
-qdbd build  PATH... -o diagram.html            # shareable interactive HTML (positions locked)
+qdbd build  PATH... -o diagram.html            # shareable interactive HTML
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG, SVG or .drawio
 qdbd layout PATH... [--reset]                  # (re)write the layout file
 qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
+qdbd path PATH... --from A --to B              # shortest join path + SQL JOIN snippet
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -152,7 +155,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.4
+      - uses: MarkPhamm/quickdbd-cli@v0.1.5
         with:
           path: erd/                 # schema file(s) or folder(s)
           output: site/index.html
@@ -176,7 +179,7 @@ Outputs are `html`, `changed` and `diff-file`.
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.4
+    rev: v0.1.5
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$   # point at your schema files

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.4"
+version = "0.1.5"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"
@@ -25,6 +25,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = ["pytest>=8", "ruff>=0.6", "fonttools>=4.50"]
+docs = ["mkdocs>=1.6,<2", "mkdocs-material>=9.5,<10"]
 
 [project.scripts]
 qdbd = "quickdbd_cli.cli:main"

quickdbd_cli-0.1.5/src/quickdbd_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.5"

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/assets/render.js

@@ -178,6 +178,41 @@
     };
   }
 
+  /* ------------------------------------------------------------------ regions: one shaded area per group */
+  var REGION_COLORS = ["#4c78a8", "#59a14f", "#e15759", "#b07aa1", "#f28e2b", "#76b7b2", "#9c755f", "#edc948"];
+  var REGION_PAD = 28, REGION_LABEL = 30;
+  function regions(model, pos, mode) {
+    var geo = geometry(model, mode), groups = {}, names = [];
+    model.tables.forEach(function (t) {
+      var g = t.group || "", p = pos[t.id];
+      if (!g || !p) return;
+      if (!groups[g]) { groups[g] = [Infinity, Infinity, -Infinity, -Infinity]; names.push(g); }
+      var b = groups[g], tg = geo[t.id];
+      b[0] = Math.min(b[0], p[0]); b[1] = Math.min(b[1], p[1]);
+      b[2] = Math.max(b[2], p[0] + tg.w); b[3] = Math.max(b[3], p[1] + tg.h);
+    });
+    var all = {};
+    model.tables.forEach(function (t) { if (t.group) all[t.group] = true; });
+    var order = Object.keys(all).sort();
+    return names.sort().map(function (g) {
+      var b = groups[g];
+      return {
+        name: g,
+        color: REGION_COLORS[order.indexOf(g) % REGION_COLORS.length],
+        x: b[0] - REGION_PAD, y: b[1] - REGION_PAD - REGION_LABEL,
+        w: b[2] - b[0] + 2 * REGION_PAD, h: b[3] - b[1] + 2 * REGION_PAD + REGION_LABEL,
+      };
+    });
+  }
+  function renderRegions(model, pos, mode) {
+    return regions(model, pos, mode).map(function (r) {
+      return '<g class="rg" data-g="' + esc(r.name) + '"><rect x="' + n(r.x) + '" y="' + n(r.y) + '" width="' + n(r.w) + '" height="' + n(r.h) +
+        '" rx="14" fill="' + r.color + '" fill-opacity="0.07" stroke="' + r.color + '" stroke-opacity="0.45" stroke-width="1.5"/>' +
+        '<text x="' + n(r.x + 16) + '" y="' + n(r.y + 22) + '" fill="' + r.color + '" font-family="' + FONT +
+        '" font-size="16" font-weight="bold">' + esc(r.name) + "</text></g>";
+    }).join("");
+  }
+
   function renderEdges(model, pos, mode, geo) {
     geo = geo || geometry(model, mode);
     return model.rels.map(function (r) { return renderEdge(model, geo, pos, r); }).join("");
@@ -186,8 +221,9 @@
   /* opts.docMarks: underline tables/columns that have doc comments (viewer only, not exports). */
   function renderInner(model, pos, mode, opts) {
     var geo = geometry(model, mode), marks = !!(opts && opts.docMarks);
+    var rg = opts && opts.regions ? '<g class="regions">' + renderRegions(model, pos, mode) + "</g>" : "";
     var tables = model.tables.map(function (t) { return pos[t.id] ? renderTable(model, t, geo[t.id], pos[t.id], marks) : ""; }).join("");
-    return '<g class="edges">' + renderEdges(model, pos, mode, geo) + '</g><g class="tables">' + tables + "</g>";
+    return rg + '<g class="edges">' + renderEdges(model, pos, mode, geo) + '</g><g class="tables">' + tables + "</g>";
   }
 
   function bounds(model, pos, mode) {
@@ -208,11 +244,16 @@
     var mode = opts.mode || "full", m = subset(model, opts.only), pad = opts.pad == null ? 40 : opts.pad;
     var edgePad = 60;
     var b = bounds(m, pos, mode);
+    if (opts.regions) {
+      regions(m, pos, mode).forEach(function (r) {
+        b = [Math.min(b[0], r.x), Math.min(b[1], r.y), Math.max(b[2], r.x + r.w), Math.max(b[3], r.y + r.h)];
+      });
+    }
     var x0 = b[0] - pad - edgePad, y0 = b[1] - pad, w = b[2] - b[0] + 2 * (pad + edgePad), h = b[3] - b[1] + 2 * pad;
     var style = opts.fontCss ? "<style>" + opts.fontCss + "</style>" : "";
     return '<svg xmlns="http://www.w3.org/2000/svg" width="' + n(w) + '" height="' + n(h) + '" viewBox="' + n(x0) + " " + n(y0) + " " + n(w) + " " + n(h) + '">' +
       style + '<rect x="' + n(x0) + '" y="' + n(y0) + '" width="' + n(w) + '" height="' + n(h) + '" fill="' + C.bg + '"/>' +
-      renderInner(m, pos, mode) + "</svg>";
+      renderInner(m, pos, mode, { regions: opts.regions }) + "</svg>";
   }
 
   /* Tables within `depth` relationship hops of `focus`. */
@@ -252,6 +293,15 @@
     }
     function n2(v) { return Math.round(v); }
     var b = bounds(m, pos, mode);
+    if (opts.regions) {
+      regions(m, pos, mode).forEach(function (r) {
+        cells.push(cell({
+          id: id(), value: r.name, vertex: "1", parent: "1",
+          style: "rounded=1;arcSize=4;whiteSpace=wrap;html=0;fillColor=" + r.color + ";opacity=12;strokeColor=" + r.color +
+            ";verticalAlign=top;align=left;spacingLeft=12;spacingTop=4;fontStyle=1;fontSize=16;fontColor=" + r.color + ";",
+        }, g(r.x - b[0] + 40, r.y - b[1] + 40, r.w + KEYW, r.h)));
+      });
+    }
     m.tables.forEach(function (t) {
       var p = pos[t.id];
       if (!p) return;
@@ -377,8 +427,70 @@
     return model.tables.filter(function (t) { return (inc === null || inc[t.id]) && !exc[t.id]; }).map(function (t) { return t.id; });
   }
 
+  /* ------------------------------------------------------------------ path finder
+   * Shortest chain of relationships between two tables (relationships are walked in either
+   * direction). Each step says which columns join. */
+  function findPath(model, from, to) {
+    if (from === to) return [];
+    var adj = {};
+    model.rels.forEach(function (r, i) {
+      (adj[r.a.t] = adj[r.a.t] || []).push({ to: r.b.t, i: i, fwd: true });
+      (adj[r.b.t] = adj[r.b.t] || []).push({ to: r.a.t, i: i, fwd: false });
+    });
+    var prev = {}, queue = [from], seen = {};
+    seen[from] = true;
+    while (queue.length) {
+      var cur = queue.shift();
+      if (cur === to) break;
+      (adj[cur] || []).forEach(function (e) {
+        if (seen[e.to]) return;
+        seen[e.to] = true;
+        prev[e.to] = { from: cur, e: e };
+        queue.push(e.to);
+      });
+    }
+    if (!seen[to]) return null;
+    var steps = [], at = to;
+    while (at !== from) {
+      var pv = prev[at], r = model.rels[pv.e.i];
+      var here = pv.e.fwd ? r.a : r.b, there = pv.e.fwd ? r.b : r.a; // here = side of pv.from
+      steps.unshift({ rel: pv.e.i, from: { t: pv.from, c: here.c, card: here.card }, to: { t: at, c: there.c, card: there.card } });
+      at = pv.from;
+    }
+    return steps;
+  }
+
+  var SQL_RESERVED = ("all and any as asc between by case check column constraint create cross default delete desc distinct " +
+    "drop else end exists foreign from full grant group having in index inner insert intersect into is join key left like " +
+    "limit not null offset on or order outer primary references right select set table then to union unique update user " +
+    "using values view when where with").split(" ");
+  function sqlIdent(name) {
+    var plain = /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && SQL_RESERVED.indexOf(name.toLowerCase()) < 0;
+    return plain ? name : '"' + name.replace(/"/g, '""') + '"';
+  }
+
+  /* SQL FROM/JOIN clause following a path. */
+  function pathSql(model, from, steps) {
+    var byId = {};
+    model.tables.forEach(function (t) { byId[t.id] = t; });
+    function col(t, c) {
+      var x = byId[t].cols.filter(function (k) { return k.id === c; })[0];
+      return x ? sqlIdent(x.name) : null;
+    }
+    var lines = ["FROM " + sqlIdent(byId[from].name)];
+    steps.forEach(function (s) {
+      var a = byId[s.from.t].name, b = byId[s.to.t].name, ca = col(s.from.t, s.from.c), cb = col(s.to.t, s.to.c);
+      if (ca && cb) lines.push("JOIN " + sqlIdent(b) + " ON " + sqlIdent(b) + "." + cb + " = " + sqlIdent(a) + "." + ca);
+      else lines.push("JOIN " + sqlIdent(b) + " ON ...  -- table-level relationship: join columns not specified");
+    });
+    return lines.join("\n");
+  }
+
   root.qdbd = {
+    findPath: findPath,
+    pathSql: pathSql,
     renderDrawio: renderDrawio,
+    regions: regions,
     select: select,
     subset: subset,
     colors: C,
@@ -394,5 +506,7 @@
   root.qdbdRenderSvg = renderSvg;
   root.qdbdSelect = select;
   root.qdbdRenderDrawio = renderDrawio;
+  root.qdbdFindPath = findPath;
+  root.qdbdPathSql = pathSql;
   root.qdbdNeighbourhood = neighbourhood;
 })(typeof window !== "undefined" ? window : globalThis);

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/assets/style.css

@@ -22,14 +22,15 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .r.hl .rb { fill: #dbe6f6; fill-opacity: 1; }
 .r:hover .rb { fill: #eef3fa; fill-opacity: 1; }
 .t.flash .tb { stroke: #f0a020; stroke-width: 3; }
-.t { cursor: pointer; }
-.serve .t { cursor: move; }
+.t { cursor: grab; }
+#canvas.panning .t { cursor: grabbing; }
 
 /* toolbar (top right, like QuickDBD's zoom controls) */
 .bar { position: absolute; top: 14px; right: 16px; display: flex; gap: 6px; align-items: center; }
 .bar button, .seg button { border: 0; background: transparent; color: #555; font: inherit; cursor: pointer;
   padding: 6px 9px; border-radius: 4px; }
 .bar button:hover, .seg button:hover { background: #e4e7ea; }
+.bar button.on { background: #fff; color: var(--blue); box-shadow: 0 1px 2px rgba(0,0,0,.12); }
 .zoomval { min-width: 48px; text-align: center; color: #666; font-variant-numeric: tabular-nums; }
 .seg { display: flex; background: #e9ecee; border-radius: 6px; padding: 2px; }
 .seg button.on { background: #fff; color: var(--blue); box-shadow: 0 1px 2px rgba(0,0,0,.12); }
@@ -110,6 +111,20 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
   padding: 8px 14px; border-radius: 6px; font-size: 12px; opacity: 0; transition: opacity .2s; pointer-events: none; z-index: 6; }
 .toast.open { opacity: 1; }
 
+/* path finder (in the details panel) */
+.details .pathbox { display: flex; gap: 6px; margin: 10px 0 4px; }
+.details .pathbox input { flex: 1; min-width: 0; padding: 5px 8px; border: 1px solid var(--line); border-radius: 5px; font: inherit; outline: none; }
+.details .pathbox input:focus { border-color: var(--blue); }
+.details .pathres ol { margin: 6px 0 8px 18px; padding: 0; }
+.details .pathres li { border: 0; padding: 2px 0; }
+.details .pathres pre { background: #f6f8fa; border: 1px solid #eceff2; border-radius: 6px; padding: 8px; font-size: 11px;
+  overflow-x: auto; margin: 6px 0; }
+.details .pathres .acts a { margin-right: 12px; font-size: 12px; }
+.details .pathres .none { margin-top: 6px; }
+.e.ph .ep { stroke: #f0a020; stroke-width: 3; }
+.e.ph path, .e.ph circle { stroke: #f0a020; }
+.t.ph .tb { stroke: #f0a020; stroke-width: 2.5; }
+
 /* diff banner (build --diff-base) */
 .diffbar { position: absolute; top: 58px; left: 50%; transform: translateX(-50%); background: #fff; border: 1px solid var(--line);
   border-radius: 8px; padding: 6px 12px; font-size: 12px; box-shadow: 0 4px 14px rgba(0,0,0,.06); display: none; z-index: 2;
@@ -165,3 +180,13 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .CodeMirror-cursor { border-left-color: #fff !important; }
 .CodeMirror-selected { background: #4a525a !important; }
 .lineerr { background: rgba(229,115,115,.18); }
+
+/* narrow screens and embedded frames: toolbar to the bottom, smaller minimap */
+@media (max-width: 900px) {
+  .bar { top: auto; bottom: 12px; right: auto; left: 12px; flex-wrap: wrap; max-width: calc(100% - 24px);
+    background: rgba(255,255,255,.92); border-radius: 8px; padding: 2px; box-shadow: 0 2px 10px rgba(0,0,0,.08); }
+  .hint { display: none; }
+  .minimap { width: 140px; height: 100px; bottom: auto; top: 14px; right: 12px; }
+  .explorer { max-width: calc(100% - 180px); }
+  .details { left: 12px; right: 12px; width: auto; top: 12px; bottom: 64px; }
+}

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/assets/viewer.js

@@ -14,6 +14,8 @@
     filter: "",
     vm: data.model, // view model: the tables/relationships left after the filter
     shown: {},
+    regions: !!data.model.regions,
+    path: null, // {to: id, steps: [...]} from the selected table
   };
   var svg = document.getElementById("canvas");
   var vp = document.getElementById("vp");
@@ -27,7 +29,7 @@
 
   /* ------------------------------------------------------------- render */
   function render() {
-    vp.innerHTML = Q.renderInner(S.vm, S.pos, S.mode, { docMarks: true });
+    vp.innerHTML = Q.renderInner(S.vm, S.pos, S.mode, { docMarks: true, regions: S.regions });
     applyFocus();
     drawMinimap();
   }
@@ -51,11 +53,15 @@
     return [r.width || 800, r.height || 600];
   }
 
-  function fit() {
-    var b = Q.bounds(S.vm, S.pos, S.mode), sz = stageSize(), pad = 40;
-    var k = Math.min((sz[0] - 2 * pad) / (b[2] - b[0]), (sz[1] - 2 * pad) / (b[3] - b[1]), 1.5);
+  function fit(only) {
+    var b = Q.bounds(only ? Q.subset(S.vm, only) : S.vm, S.pos, S.mode), sz = stageSize(), pad = 40;
+    if (S.regions && !only) b = [b[0] - 30, b[1] - 60, b[2] + 30, b[3] + 30]; // room for region borders and labels
+    if (only) sz = [sz[0] - (details.classList.contains("open") ? 400 : 0), sz[1]]; // keep clear of the details panel
+    // Keep clear of the floating search box / toolbar at the top and, on narrow screens, the toolbar at the bottom.
+    var top = 70, bottom = sz[0] < 900 ? 70 : pad, availH = sz[1] - top - bottom;
+    var k = Math.min((sz[0] - 2 * pad) / (b[2] - b[0]), availH / (b[3] - b[1]), 1.5);
     k = Math.max(k, 0.05);
-    S.view = { k: k, x: (sz[0] - (b[2] - b[0]) * k) / 2 - b[0] * k, y: (sz[1] - (b[3] - b[1]) * k) / 2 - b[1] * k };
+    S.view = { k: k, x: (sz[0] - (b[2] - b[0]) * k) / 2 - b[0] * k, y: top + (availH - (b[3] - b[1]) * k) / 2 - b[1] * k };
     applyView();
   }
 
@@ -94,6 +100,28 @@
   }
 
   function applyFocus() {
+    vp.querySelectorAll(".ph").forEach(function (el) { el.classList.remove("ph"); });
+    if (S.path && S.focus && S.path.steps) {
+      var on = {}, edges = [];
+      on[S.focus] = true;
+      S.path.steps.forEach(function (st) { on[st.to.t] = true; edges.push(st); });
+      svg.classList.add("focus");
+      vp.querySelectorAll(".t").forEach(function (el) {
+        var id = el.getAttribute("data-id");
+        el.classList.toggle("dim", !on[id]);
+        el.classList.toggle("ph", !!on[id]);
+      });
+      vp.querySelectorAll(".e").forEach(function (el) {
+        var a = el.getAttribute("data-a"), ac = el.getAttribute("data-ac"), b = el.getAttribute("data-b"), bc = el.getAttribute("data-bc");
+        var hit = edges.some(function (st) {
+          return (st.from.t === a && st.from.c === ac && st.to.t === b && st.to.c === bc) ||
+            (st.from.t === b && st.from.c === bc && st.to.t === a && st.to.c === ac);
+        });
+        el.classList.toggle("dim", !hit);
+        el.classList.toggle("ph", hit);
+      });
+      return;
+    }
     if (!S.focus || !byId[S.focus]) {
       S.focus = null;
       svg.classList.remove("focus");
@@ -180,12 +208,13 @@
     if (ev.button !== 0) return;
     var tEl = ev.target.closest && ev.target.closest(".t");
     drag = { sx: ev.clientX, sy: ev.clientY, moved: false, table: tEl ? tEl.getAttribute("data-id") : null, el: tEl };
-    if (drag.table && S.serve) {
+    if (drag.table) { // tables are draggable everywhere; only `qdbd serve` saves the new position
       drag.start = S.pos[drag.table].slice();
+      tEl.parentNode.appendChild(tEl); // bring the grabbed table to the front
     } else {
       drag.view = { x: S.view.x, y: S.view.y };
-      svg.classList.add("panning");
     }
+    svg.classList.add("panning");
     svg.setPointerCapture(ev.pointerId);
   });
   var raf = null;
@@ -215,6 +244,7 @@
       return;
     }
     if (d.start) {
+      if (S.regions) render(); // regions are sized from table positions
       drawMinimap();
       var name = byId[d.table].name, body = {};
       body[name] = S.pos[d.table];
@@ -235,13 +265,28 @@
   function center() { var s = stageSize(); return [s[0] / 2, s[1] / 2]; }
   document.getElementById("zin").onclick = function () { var c = center(); zoomAt(1.25, c[0], c[1]); };
   document.getElementById("zout").onclick = function () { var c = center(); zoomAt(0.8, c[0], c[1]); };
-  document.getElementById("zfit").onclick = fit;
+  document.getElementById("zfit").onclick = function () { fit(); };
   document.querySelectorAll("#modes button").forEach(function (b) {
     b.onclick = function () {
       setMode(b.getAttribute("data-mode"));
     };
   });
 
+  var regionBtn = document.getElementById("xregions");
+  function groupCount() {
+    var g = {};
+    S.model.tables.forEach(function (t) { if (t.group) g[t.group] = true; });
+    return Object.keys(g).length;
+  }
+  function setRegions(on) {
+    S.regions = !!on && groupCount() > 0;
+    regionBtn.classList.toggle("on", S.regions);
+    regionBtn.style.display = groupCount() > 1 ? "" : "none";
+    render();
+    scheduleHash();
+  }
+  regionBtn.onclick = function () { setRegions(!S.regions); };
+
   function setMode(mode) {
     S.mode = ["full", "keys", "header"].indexOf(mode) >= 0 ? mode : "full";
     document.querySelectorAll("#modes button").forEach(function (o) { o.classList.toggle("on", o.getAttribute("data-mode") === S.mode); });
@@ -251,6 +296,7 @@
 
   /* ------------------------------------------------------------- selection: focus + details */
   function select(id, opts) {
+    if ((id || null) !== S.focus) S.path = null;
     S.focus = id && byId[id] ? id : null;
     scheduleHash();
     applyFocus();
@@ -431,6 +477,10 @@
     if (t.file) meta.push(Q.esc(t.file) + ":" + t.line);
     if (meta.length) out.push('<div class="meta">' + meta.join(" &middot; ") + "</div>");
     if (t.doc) out.push('<div class="doc">' + Q.esc(t.doc) + "</div>");
+    out.push('<div class="pathbox"><input id="pathto" list="pathlist" placeholder="Path to another table…" autocomplete="off" value="' +
+      (S.path && byId[S.path.to] ? Q.esc(byId[S.path.to].name) : "") + '"></div><datalist id="pathlist">' +
+      S.vm.tables.filter(function (x) { return x.id !== id; }).map(function (x) { return '<option value="' + Q.esc(x.name) + '">'; }).join("") +
+      '</datalist><div class="pathres" id="pathres">' + pathHtml(id) + "</div>");
     if (t.diff && t.diff.state === "changed") {
       var base = (S.model.diff && S.model.diff.base) || "base", ch = [];
       t.cols.forEach(function (c) {
@@ -460,6 +510,47 @@
     details.classList.add("open");
     document.getElementById("stage").classList.add("has-details");
   }
+  /* ------------------------------------------------------------- path finder */
+  function pathHtml(id) {
+    if (!S.path) return "";
+    var to = byId[S.path.to];
+    if (!S.path.steps) return '<div class="none">No relationship path from ' + Q.esc(byId[id].name) + " to " + Q.esc(to.name) + " (with the current filter).</div>";
+    var items = S.path.steps.map(function (st) {
+      return "<li>" + link(st.from.t, st.from.c) + " &rarr; " + link(st.to.t, st.to.c) +
+        '<span class="card">' + CARD[st.from.card] + ":" + CARD[st.to.card] + "</span></li>";
+    }).join("");
+    return "<h3>Path to " + Q.esc(to.name) + " (" + S.path.steps.length + " join" + (S.path.steps.length === 1 ? "" : "s") + ")</h3><ol>" + items +
+      "</ol><pre>" + Q.esc(Q.pathSql(S.vm, id, S.path.steps)) + '</pre><div class="acts"><a id="pathsql">Copy SQL</a><a id="pathonly">Show only this path</a><a id="pathclear">Clear</a></div>';
+  }
+  function findPathTo(name) {
+    var target = null;
+    S.vm.tables.forEach(function (t) { if (t.name.toLowerCase() === String(name).trim().toLowerCase()) target = t.id; });
+    if (!S.focus || !target || target === S.focus) return false;
+    S.path = { to: target, steps: Q.findPath(S.vm, S.focus, target) };
+    showDetails(S.focus);
+    applyFocus();
+    if (S.path.steps && !applyingHash) fit([S.focus].concat(S.path.steps.map(function (st) { return st.to.t; })));
+    scheduleHash();
+    return true;
+  }
+  dbody.addEventListener("keydown", function (ev) {
+    if (ev.target.id === "pathto" && ev.key === "Enter") findPathTo(ev.target.value);
+    if (ev.target.id === "pathto" && ev.key === "Escape") ev.stopPropagation();
+  });
+  dbody.addEventListener("change", function (ev) { if (ev.target.id === "pathto") findPathTo(ev.target.value); });
+  dbody.addEventListener("click", function (ev) {
+    if (ev.target.id === "pathclear") { S.path = null; showDetails(S.focus); applyFocus(); scheduleHash(); }
+    else if (ev.target.id === "pathonly" && S.path && S.path.steps) {
+      var names = [byId[S.focus].name].concat(S.path.steps.map(function (st) { return byId[st.to.t].name; }));
+      // Selector syntax treats spaces, commas, + and a leading ! specially; match those characters with "?".
+      applyFilter(names.map(function (n) { return n.replace(/[\s,+!]/g, "?"); }).join(" "));
+    } else if (ev.target.id === "pathsql" && S.path && S.path.steps) {
+      var sql = Q.pathSql(S.vm, S.focus, S.path.steps);
+      if (navigator.clipboard && window.isSecureContext) navigator.clipboard.writeText(sql).then(function () { showToast("SQL copied"); });
+      else window.prompt("Copy SQL:", sql);
+    }
+  });
+
   function closeDetails() {
     details.classList.remove("open");
     document.getElementById("stage").classList.remove("has-details");
@@ -519,14 +610,14 @@
   }
   function exportSvg() {
     var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
-    return Q.renderSvg(S.vm, S.pos, { mode: S.mode, only: only, fontCss: document.getElementById("qdbd-font").textContent });
+    return Q.renderSvg(S.vm, S.pos, { mode: S.mode, only: only, regions: S.regions, fontCss: document.getElementById("qdbd-font").textContent });
   }
   document.getElementById("xsvg").onclick = function () {
     download((data.title || "diagram") + ".svg", new Blob([exportSvg()], { type: "image/svg+xml" }));
   };
   document.getElementById("xdrawio").onclick = function () {
     var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
-    var xml = Q.renderDrawio(S.vm, S.pos, { mode: S.mode, only: only, title: data.title || "ERD" });
+    var xml = Q.renderDrawio(S.vm, S.pos, { mode: S.mode, only: only, title: data.title || "ERD", regions: S.regions });
     download((data.title || "diagram") + ".drawio", new Blob([xml], { type: "application/xml" }));
   };
   document.getElementById("xpng").onclick = function () {
@@ -564,6 +655,9 @@
 
   index();
   if (S.serve) document.body.classList.add("serve");
+  if (stageSize()[0] < 900) explorer.classList.add("collapsed"); // small screens / embedded frames
+  regionBtn.classList.toggle("on", S.regions);
+  regionBtn.style.display = groupCount() > 1 ? "" : "none";
   computeView();
   render();
   drawTree();
@@ -597,7 +691,9 @@
     var p = new URLSearchParams(), v = S.view, sz = stageSize();
     if (S.filter) p.set("f", S.filter);
     if (S.focus && byId[S.focus]) p.set("t", byId[S.focus].name);
+    if (S.path && byId[S.path.to]) p.set("p", byId[S.path.to].name);
     if (S.mode !== "full") p.set("m", S.mode);
+    if (S.regions !== !!S.model.regions) p.set("r", S.regions ? "1" : "0");
     p.set("z", String(Math.round(v.k * 1000) / 1000));
     p.set("c", Math.round((sz[0] / 2 - v.x) / v.k) + "," + Math.round((sz[1] / 2 - v.y) / v.k));
     return "#" + p.toString();
@@ -615,10 +711,12 @@
     applyingHash = true;
     try {
       if (p.has("m")) setMode(p.get("m"));
+      if (p.has("r")) setRegions(p.get("r") === "1");
       applyFilter(p.get("f") || "", true);
       var name = p.get("t"), id = null;
       if (name) S.model.tables.forEach(function (t) { if (t.name === name) id = t.id; });
       select(id && S.shown[id] ? id : null);
+      if (p.get("p") && S.focus) findPathTo(p.get("p"));
       var z = parseFloat(p.get("z")), c = (p.get("c") || "").split(",").map(Number);
       if (z > 0 && c.length === 2 && !isNaN(c[0]) && !isNaN(c[1])) {
         var sz = stageSize();

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/cli.py

@@ -11,6 +11,7 @@ from .model import Schema
 from .project import Project, SelectionError, selector_expr
 
 OK = "No errors found. Good job!"
+BY_GROUP_HELP = "fresh layout that keeps each file / dbt folder together, with regions (ignores saved positions)"
 
 
 def _print_diagnostics(schema: Schema, strict: bool) -> bool:
@@ -58,7 +59,7 @@ def cmd_build(args) -> int:
             # Diff first so `diff:` selectors work; then select.
             from . import diff
 
-            model, pos = project.build(schema)
+            model, pos = project.build(schema, by_group=args.by_group)
             old = diff.schema_at_ref(args.diff_base, project.inputs)
             diff.annotate_model(model, diff.diff_schemas(old, schema), args.diff_base)
             expr = selector_expr(args.select, args.exclude)
@@ -68,7 +69,7 @@ def cmd_build(args) -> int:
                 model = select_model(model, expr)
                 pos = {k: v for k, v in pos.items() if any(t["id"] == k for t in model["tables"])}
         else:
-            model, pos = project.build(schema, select=selector_expr(args.select, args.exclude))
+            model, pos = project.build(schema, select=selector_expr(args.select, args.exclude), by_group=args.by_group)
     except SelectionError as e:
         print(f"error: {e}", file=sys.stderr)
         return 1
@@ -94,12 +95,13 @@ def cmd_export(args) -> int:
     if not _print_diagnostics(schema, args.strict):
         return 1
     try:
-        model, pos = project.build(schema, select=selector_expr(args.select, args.exclude))
+        model, pos = project.build(schema, select=selector_expr(args.select, args.exclude), by_group=args.by_group)
     except SelectionError as e:
         print(f"error: {e}", file=sys.stderr)
         return 1
+    regions = args.regions or args.by_group
     only = None
-    if not args.focus and (args.select or args.exclude):
+    if not args.focus and (args.select or args.exclude) and not args.by_group:
         only = [t["id"] for t in model["tables"]]
         pos = export.focus_positions(model, pos, only)  # compact layout for the selection
     if args.focus:
@@ -117,11 +119,12 @@ def cmd_export(args) -> int:
     out.parent.mkdir(parents=True, exist_ok=True)
     if fmt == "drawio":
         out.write_text(
-            export.render_drawio(model, pos, only=only, mode=args.mode, title=_title(project)), encoding="utf-8"
+            export.render_drawio(model, pos, only=only, mode=args.mode, title=_title(project), regions=regions),
+            encoding="utf-8",
         )
         print(f"Wrote {out} ({len(only) if only else len(model['tables'])} tables)")
         return 0
-    svg = export.render_svg(model, pos, only=only, mode=args.mode, embed_font=(fmt == "svg"))
+    svg = export.render_svg(model, pos, only=only, mode=args.mode, embed_font=(fmt == "svg"), regions=regions)
     if fmt == "svg":
         out.write_text(svg, encoding="utf-8")
     else:
@@ -135,7 +138,7 @@ def cmd_layout(args) -> int:
     schema = project.compile()
     if not _print_diagnostics(schema, False):
         return 1
-    model, pos = project.build(schema, reset=args.reset)
+    model, pos = project.build(schema, reset=args.reset, by_group=args.by_group)
     project.save_positions(model, pos)
     print(f"Wrote {project.sidecar} ({len(pos)} tables)")
     return 0
@@ -178,6 +181,48 @@ def cmd_import_dbt(args) -> int:
     return 0
 
 
+def cmd_path(args) -> int:
+    from . import export
+    from .jsrt import runtime
+
+    project = _open(args)
+    schema = project.compile()
+    if not _print_diagnostics(schema, False):
+        return 1
+    from .measure import model_json
+
+    model = model_json(schema)
+    ends = []
+    for name in (args.source, args.target):
+        t = export.find_table(model, name)
+        if t is None:
+            print(f"error: table '{name}' not found", file=sys.stderr)
+            return 1
+        ends.append(t)
+    rt = runtime()
+    rt.load("render.js")
+    steps = rt.call("qdbdFindPath", model, ends[0]["id"], ends[1]["id"])
+    a, b = ends[0]["name"], ends[1]["name"]
+    if steps is None:
+        print(f"No relationship path between {a} and {b}.")
+        return 1
+    by_id = {t["id"]: t for t in model["tables"]}
+    card = {"one": "1", "many": "N", "zeroOne": "0..1", "zeroMany": "0..N"}
+
+    def end(e):
+        t = by_id[e["t"]]
+        col = next((c["name"] for c in t["cols"] if c["id"] == e["c"]), None)
+        return f"{t['name']}.{col}" if col else t["name"]
+
+    print(f"{a} -> {b}: {len(steps)} join(s)")
+    for st in steps:
+        print(f"  {end(st['from'])} -> {end(st['to'])} ({card[st['from']['card']]}:{card[st['to']['card']]})")
+    if steps:
+        print()
+        print(rt.call("qdbdPathSql", model, ends[0]["id"], steps))
+    return 0
+
+
 def cmd_diff(args) -> int:
     from . import diff
 
@@ -252,6 +297,7 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument(
         "--diff-base", metavar="GIT_REF", help="colour tables/columns changed since this git ref (e.g. origin/main)"
     )
+    sp.add_argument("--by-group", action="store_true", help=BY_GROUP_HELP)
     sp.add_argument("--layout", help="layout sidecar file (default: next to the schema)")
     sp.add_argument("--strict", action="store_true")
     sp.set_defaults(func=cmd_build)
@@ -264,6 +310,8 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--depth", type=int, default=1, help="relationship hops around --focus (default 1)")
     sp.add_argument("--mode", choices=["full", "keys", "header"], default="full", help="collapse mode")
     sp.add_argument("--scale", type=float, default=2.0, help="PNG pixel scale (default 2)")
+    sp.add_argument("--regions", action="store_true", help="draw a shaded area per file / dbt folder")
+    sp.add_argument("--by-group", action="store_true", help=BY_GROUP_HELP)
     sp.add_argument("--layout")
     sp.add_argument("--strict", action="store_true")
     sp.set_defaults(func=cmd_export)
@@ -271,9 +319,16 @@ def build_parser() -> argparse.ArgumentParser:
     sp = sub.add_parser("layout", help="write table positions to the layout sidecar")
     paths(sp)
     sp.add_argument("--reset", action="store_true", help="discard saved positions and auto-layout everything")
+    sp.add_argument("--by-group", action="store_true", help=BY_GROUP_HELP)
     sp.add_argument("--layout")
     sp.set_defaults(func=cmd_layout)
 
+    sp = sub.add_parser("path", help="shortest join path between two tables, with a SQL JOIN snippet")
+    paths(sp)
+    sp.add_argument("--from", dest="source", required=True, metavar="TABLE")
+    sp.add_argument("--to", dest="target", required=True, metavar="TABLE")
+    sp.set_defaults(func=cmd_path)
+
     sp = sub.add_parser("diff", help="compare schema versions (two paths, or --base GIT_REF vs working tree)")
     sp.add_argument("paths", nargs="+", metavar="PATH", help="OLD NEW, or the schema path(s) with --base")
     sp.add_argument("--base", metavar="GIT_REF", help="compare PATH(s) at this git ref with the working tree")

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/export.py

@@ -45,23 +45,35 @@ def focus_ids(model: dict, table_id: str, depth: int) -> list[str]:
 
 
 def render_svg(
-    model: dict, positions: dict, only: list[str] | None = None, mode: str = "full", embed_font: bool = True
+    model: dict,
+    positions: dict,
+    only: list[str] | None = None,
+    mode: str = "full",
+    embed_font: bool = True,
+    regions: bool = False,
 ) -> str:
     rt = runtime()
     rt.load("render.js")
-    opts = {"mode": mode, "only": only}
+    opts = {"mode": mode, "only": only, "regions": regions}
     if embed_font:
         opts["fontCss"] = font_css()
     return rt.call("qdbdRenderSvg", model, positions, opts)
 
 
 def render_drawio(
-    model: dict, positions: dict, only: list[str] | None = None, mode: str = "full", title: str = "ERD"
+    model: dict,
+    positions: dict,
+    only: list[str] | None = None,
+    mode: str = "full",
+    title: str = "ERD",
+    regions: bool = False,
 ) -> str:
     """draw.io / diagrams.net file (mxGraph XML) with editable ER tables."""
     rt = runtime()
     rt.load("render.js")
-    return rt.call("qdbdRenderDrawio", model, positions, {"mode": mode, "only": only, "title": title})
+    return rt.call(
+        "qdbdRenderDrawio", model, positions, {"mode": mode, "only": only, "title": title, "regions": regions}
+    )
 
 
 def focus_positions(model: dict, positions: dict, ids: list[str]) -> dict:

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/html.py

@@ -51,6 +51,7 @@ BODY = """
         <button data-mode="header">Names</button>
       </div>
       <div class="sep"></div>
+      <button id="xregions" title="Shade an area per file / dbt folder">Regions</button>
       <button id="xlink" title="Copy a link to this exact view (filter, selected table, zoom)">Link</button>
       <div class="sep"></div>
       <button id="xsvg" title="Export SVG">SVG</button>
@@ -93,9 +94,9 @@ FILTER_HELP = (
 def render_page(model: dict, positions: dict, title: str, serve: bool = False) -> str:
     data = {"model": model, "positions": positions, "serve": serve, "title": title}
     hint = (
-        "Drag tables to move them (saved). Click a table to focus. Esc clears."
+        "Drag tables to arrange them (saved). Click a table for details. Esc clears."
         if serve
-        else "Click a table to focus its relationships. Esc clears. Scroll to zoom, drag to pan."
+        else "Drag tables to rearrange (not saved). Click a table for details. Scroll to zoom, drag empty space to pan."
     )
     body = BODY.format(side=SIDE if serve else "", count=len(model["tables"]), hint=hint, filter_help=FILTER_HELP)
     head_extra = ""

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/layout.py

@@ -63,6 +63,7 @@ def elk_layout(tables: list[dict], rels: list[dict]) -> Positions:
         "edges": edges,
     }
     first = rt.call_async("qdbdElkLayout", graph)
+    first = _landscape(tables, {k: (v[0], v[1]) for k, v in first.items()})
     graph = {
         "id": "root",
         "layoutOptions": OVERLAP_OPTIONS,
@@ -78,6 +79,59 @@ def elk_layout(tables: list[dict], rels: list[dict]) -> Positions:
     return {k: (int(v[0] - min_x), int(v[1] - min_y)) for k, v in raw.items()}
 
 
+def _bbox(tables: list[dict], pos: dict) -> tuple[float, float]:
+    xs = [pos[t["id"]][0] for t in tables] + [pos[t["id"]][0] + t["w"] for t in tables]
+    ys = [pos[t["id"]][1] for t in tables] + [pos[t["id"]][1] + t["h"] for t in tables]
+    return max(xs) - min(xs), max(ys) - min(ys)
+
+
+def _landscape(tables: list[dict], pos: dict) -> dict:
+    """Stress layout picks an arbitrary orientation; turn tall results 90 degrees so they fit screens."""
+    w, h = _bbox(tables, pos)
+    if h <= w * 1.15:
+        return pos
+    out = {}
+    for t in tables:
+        cx, cy = pos[t["id"]][0] + t["w"] / 2, pos[t["id"]][1] + t["h"] / 2
+        nx, ny = cy, -cx  # rotate centres; table boxes stay upright
+        out[t["id"]] = (nx - t["w"] / 2, ny - t["h"] / 2)
+    return out
+
+
+GROUP_GAP = 140  # room for region padding + label between groups
+
+
+def group_layout(tables: list[dict], rels: list[dict]) -> Positions:
+    """Lay out each group (file / dbt folder) on its own, then pack the groups as blocks.
+
+    Keeps a folder's tables together so regions don't overlap. Cross-group relationships are drawn
+    but don't influence placement.
+    """
+    groups: dict[str, list[dict]] = {}
+    for t in tables:
+        groups.setdefault(t.get("group") or "", []).append(t)
+    if len(groups) <= 1:
+        return elk_layout(tables, rels)
+    blocks = []
+    for name in sorted(groups):
+        members = groups[name]
+        pos = elk_layout(members, rels)
+        w, h = _bbox(members, pos)
+        blocks.append((name, pos, w, h))
+    total = sum((w + GROUP_GAP) * (h + GROUP_GAP) for _, _, w, h in blocks)
+    row_w = max(max(w for _, _, w, _ in blocks), (total * 1.6) ** 0.5)
+    out: Positions = {}
+    x = y = row_h = 0.0
+    for _name, pos, w, h in sorted(blocks, key=lambda b: (-b[3], b[0])):
+        if x > 0 and x + w > row_w:
+            x, y, row_h = 0.0, y + row_h + GROUP_GAP, 0.0
+        for k, (px, py) in pos.items():
+            out[k] = (int(px + x), int(py + y))
+        x += w + GROUP_GAP
+        row_h = max(row_h, h)
+    return out
+
+
 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:

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/src/quickdbd_cli/project.py

@@ -58,7 +58,9 @@ class Project:
     def compile(self) -> Schema:
         return compile_sources(self.sources())
 
-    def build(self, schema: Schema, reset: bool = False, select: str | None = None) -> tuple[dict, dict]:
+    def build(
+        self, schema: Schema, reset: bool = False, select: str | None = None, by_group: bool = False
+    ) -> tuple[dict, dict]:
         """Returns (model, positions) with positions keyed by table id as [x, y].
 
         ``select`` is a dbt-style selector expression (see ``select_model``); unselected tables are dropped.
@@ -66,6 +68,10 @@ class Project:
         model = model_json(schema)
         if select:
             model = select_model(model, select)
+        if by_group:  # fresh grouped layout; saved positions are ignored
+            model["regions"] = True
+            pos = layout.group_layout(model["tables"], model["rels"])
+            return model, {k: [v[0], v[1]] for k, v in pos.items()}
         side = {} if reset else layout.read_sidecar(self.sidecar)
         pos = layout.resolve_positions(model, side, schema.layout, reset=reset)
         return model, {k: [v[0], v[1]] for k, v in pos.items()}

quickdbd_cli-0.1.5/tests/test_path.py

@@ -0,0 +1,67 @@
+"""Path finder (render.js findPath / pathSql) and `qdbd path`."""
+
+from quickdbd_cli.cli import main
+from quickdbd_cli.jsrt import runtime
+from quickdbd_cli.measure import model_json
+from quickdbd_cli.parser import compile_text
+
+SCHEMA = """customers
+-
+customer_id PK int
+
+"Order"
+-
+order_id PK int
+customer_id int FK >- customers.customer_id
+
+payments
+-
+payment_id PK int
+order_id int FK >- Order.order_id
+
+island
+-
+id PK int
+"""
+
+
+def js(fn, *args):
+    rt = runtime()
+    rt.load("render.js")
+    return rt.call(fn, *args)
+
+
+def test_find_path_both_directions():
+    m = model_json(compile_text(SCHEMA))
+    steps = js("qdbdFindPath", m, "payments", "customers")
+    assert [(s["from"]["t"], s["from"]["c"], s["to"]["t"], s["to"]["c"]) for s in steps] == [
+        ("payments", "order_id", "Order", "order_id"),
+        ("Order", "customer_id", "customers", "customer_id"),
+    ]
+    back = js("qdbdFindPath", m, "customers", "payments")
+    assert [s["to"]["t"] for s in back] == ["Order", "payments"]
+    assert js("qdbdFindPath", m, "payments", "island") is None
+    assert js("qdbdFindPath", m, "payments", "payments") == []
+
+
+def test_path_sql_quotes_reserved_words():
+    m = model_json(compile_text(SCHEMA))
+    steps = js("qdbdFindPath", m, "payments", "customers")
+    assert js("qdbdPathSql", m, "payments", steps) == (
+        "FROM payments\n"
+        'JOIN "Order" ON "Order".order_id = payments.order_id\n'
+        'JOIN customers ON customers.customer_id = "Order".customer_id'
+    )
+
+
+def test_cli_path(tmp_path, capsys):
+    f = tmp_path / "s.txt"
+    f.write_text(SCHEMA)
+    assert main(["path", str(f), "--from", "payments", "--to", "customers"]) == 0
+    out = capsys.readouterr().out
+    assert out.startswith("payments -> customers: 2 join(s)")
+    assert "payments.order_id -> Order.order_id (N:1)" in out
+    assert 'JOIN "Order" ON' in out
+    assert main(["path", str(f), "--from", "payments", "--to", "island"]) == 1
+    assert "No relationship path" in capsys.readouterr().out
+    assert main(["path", str(f), "--from", "nope", "--to", "island"]) == 1

{quickdbd_cli-0.1.4 → quickdbd_cli-0.1.5}/tests/test_pipeline.py

@@ -268,3 +268,61 @@ def test_drawio_export_with_selection(tmp_path, capsys):
     assert main(["export", str(SYNTH), "-s", "Customer+1", "-o", str(out)]) == 0
     assert "Wrote" in capsys.readouterr().out
     assert out.read_text().count("shape=table;") >= 2
+
+
+def test_small_schema_layout_is_landscape():
+    p = Project.open([SAMPLE])
+    m = model_json(p.compile())
+    pos = layout.elk_layout(m["tables"], m["rels"])
+    w, h = layout._bbox(m["tables"], pos)
+    assert w >= h  # chain-shaped schemas used to come out tall and narrow
+
+
+def test_landscape_rotation_keeps_tables_upright():
+    tables = [{"id": "a", "w": 100, "h": 50}, {"id": "b", "w": 100, "h": 50}]
+    tall = {"a": (0, 0), "b": (0, 400)}
+    out = layout._landscape(tables, tall)
+    w, h = layout._bbox(tables, out)
+    assert w > h
+    assert layout._landscape(tables, out) == out  # already landscape: unchanged
+
+
+def test_group_layout_keeps_folders_apart():
+    p = Project.open([SYNTH])
+    m = model_json(p.compile())
+    pos = layout.group_layout(m["tables"], m["rels"])
+    assert len(pos) == 200
+    boxes = {}
+    for t in m["tables"]:
+        x, y = pos[t["id"]]
+        b = boxes.setdefault(t["group"], [x, y, x + t["w"], y + t["h"]])
+        b[:] = [min(b[0], x), min(b[1], y), max(b[2], x + t["w"]), max(b[3], y + t["h"])]
+    rects = [(b[0], b[1], b[2] - b[0], b[3] - b[1]) for b in boxes.values()]
+    assert len(rects) == 5
+    assert not any(_overlap(r1, r2) for i, r1 in enumerate(rects) for r2 in rects[i + 1 :])
+
+
+def test_by_group_cli(tmp_path, capsys):
+    work = tmp_path / "s"
+    shutil.copytree(SYNTH, work)
+    html = tmp_path / "g.html"
+    assert main(["build", str(work), "--by-group", "-o", str(html)]) == 0
+    assert '"regions":true' in html.read_text()
+    svg = tmp_path / "g.svg"
+    assert main(["export", str(work), "--by-group", "-o", str(svg)]) == 0
+    assert svg.read_text().count('class="rg"') == 5
+    drawio = tmp_path / "g.drawio"
+    assert main(["export", str(work), "--regions", "-o", str(drawio)]) == 0
+    assert drawio.read_text().count("verticalAlign=top;align=left;spacingLeft=12") == 5
+    before = (work / "qdbd.layout.json").read_text()
+    assert main(["layout", str(work), "--by-group"]) == 0
+    assert (work / "qdbd.layout.json").read_text() != before
+
+
+def test_regions_skip_ungrouped_tables():
+    from quickdbd_cli.jsrt import runtime
+
+    m = model_json(compile_text(SMALL, "one.txt"))
+    rt = runtime()
+    rt.load("render.js")
+    assert rt.call("qdbd.regions", m, {"Customer": [0, 0], "Order": [300, 0]}, "full") == []

quickdbd_cli-0.1.4/src/quickdbd_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.4"