quickdbd-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.1
+Version: 0.1.3
 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
@@ -55,12 +55,33 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
+  - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons
 - **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.
 - **Pip-only install:** no Graphviz, Node or browser needed. Layout uses [ELK](https://eclipse.dev/elk/), running in an embedded V8.
 - **CI-friendly:** builds are deterministic, and errors are `file:line: error: …` with exit code 1.
 
+## From a dbt project
+
+```bash
+dbt docs generate                                   # optional: adds real column types (catalog.json)
+qdbd import dbt target/manifest.json -o erd/        # one .txt per folder (staging, marts, sources, ...)
+qdbd build erd/ -o erd.html
+```
+
+- **Tables:** models, seeds and snapshots of your project, plus sources.
+- **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
+- **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
+- **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **Options:**
+  - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
+  - `--package all` includes installed packages
+  - `--no-sources` drops sources
+  - `-o schema.txt` writes a single file
+
+Re-running the import overwrites the generated files. Table positions survive because they live in the layout file, keyed by table name.
+
 ## Commands
 
 ```bash
@@ -69,6 +90,7 @@ qdbd build  PATH... -o diagram.html            # shareable interactive HTML (pos
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG or SVG image
 qdbd layout PATH... [--reset]                  # (re)write the layout file
+qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -157,7 +179,7 @@ TWINE_USERNAME=__token__
 TWINE_PASSWORD=pypi-...
 ```
 
-Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
+Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `PATH="$PWD/.venv/bin:$PATH" scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
 
 ## License
 

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/README.md

@@ -30,12 +30,33 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
+  - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons
 - **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.
 - **Pip-only install:** no Graphviz, Node or browser needed. Layout uses [ELK](https://eclipse.dev/elk/), running in an embedded V8.
 - **CI-friendly:** builds are deterministic, and errors are `file:line: error: …` with exit code 1.
 
+## From a dbt project
+
+```bash
+dbt docs generate                                   # optional: adds real column types (catalog.json)
+qdbd import dbt target/manifest.json -o erd/        # one .txt per folder (staging, marts, sources, ...)
+qdbd build erd/ -o erd.html
+```
+
+- **Tables:** models, seeds and snapshots of your project, plus sources.
+- **Relationships:** `relationships` tests (including dbt_utils `relationships_where`) and `foreign_key` constraints.
+- **Primary keys:** `primary_key` constraints, or else a column with both `unique` and `not_null` tests.
+- **Docs:** model and column descriptions become doc comments, shown as tooltips.
+- **Options:**
+  - `--select 'marts.*'` narrows by name, fqn or path (repeatable)
+  - `--package all` includes installed packages
+  - `--no-sources` drops sources
+  - `-o schema.txt` writes a single file
+
+Re-running the import overwrites the generated files. Table positions survive because they live in the layout file, keyed by table name.
+
 ## Commands
 
 ```bash
@@ -44,6 +65,7 @@ qdbd build  PATH... -o diagram.html            # shareable interactive HTML (pos
 qdbd serve  PATH... [--port 8765]              # live editor + drag-to-arrange
 qdbd export PATH... -o out.png [--focus Customer --depth 1]   # PNG or SVG image
 qdbd layout PATH... [--reset]                  # (re)write the layout file
+qdbd import dbt target/manifest.json -o erd/   # generate schema files from a dbt project
 ```
 
 `PATH` is a `.txt` file or a folder. Every `*.txt` under a folder is read recursively.
@@ -132,7 +154,7 @@ TWINE_USERNAME=__token__
 TWINE_PASSWORD=pypi-...
 ```
 
-Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
+Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `PATH="$PWD/.venv/bin:$PATH" scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
 
 ## License
 

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/scripts/release.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # Build and upload the current version to PyPI using credentials from .env,
 # then tag and create the GitHub release.
-# Usage: bump `version` in pyproject.toml and src/quickdbd_cli/__init__.py, commit, then run scripts/release.sh
+# Usage: bump `version` in pyproject.toml and src/quickdbd_cli/__init__.py, commit, then run
+#   PATH="$PWD/.venv/bin:$PATH" scripts/release.sh
 set -euo pipefail
 cd "$(dirname "$0")/.."
 
@@ -12,7 +13,11 @@ version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','
 [ -z "$(git status --porcelain --untracked-files=no)" ] || { echo "error: uncommitted changes" >&2; exit 1; }
 
 rm -rf dist
-python3 -m pip install -q --upgrade build twine
+# uv-created venvs have no pip; only install the tools when they're missing.
+python3 -c "import build, twine" 2>/dev/null || {
+  if command -v uv >/dev/null; then uv pip install -q --python "$(command -v python3)" build twine
+  else python3 -m pip install -q --upgrade build twine; fi
+}
 python3 -m build
 python3 -m twine check dist/*
 python3 -m twine upload --non-interactive dist/*

quickdbd_cli-0.1.3/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/src/quickdbd_cli/assets/render.js

@@ -66,13 +66,22 @@
       '<path d="M' + n(x + 6.5) + " " + n(cy) + "h7m-2 0v3m-2.5-3v2" + '"/></g>';
   }
 
-  function renderTable(model, t, g, p) {
+  /* Dotted underline marking text that has a doc comment (interactive viewer only). */
+  function docMark(x, y, w, color) {
+    return '<line class="dm" x1="' + n(x) + '" y1="' + n(y) + '" x2="' + n(x + w) + '" y2="' + n(y) +
+      '" stroke="' + color + '" stroke-width="1" stroke-dasharray="1.5 2"/>';
+  }
+
+  function renderTable(model, t, g, p, docMarks) {
     var st = model.style, w = g.w, h = g.h, out = [];
     out.push('<g class="t" data-id="' + esc(t.id) + '" transform="translate(' + n(p[0]) + "," + n(p[1]) + ')">');
     out.push('<rect class="tb" width="' + w + '" height="' + h + '" rx="2" fill="' + C.body + '" stroke="' + C.border + '"/>');
     out.push('<path class="th" d="M0 2a2 2 0 0 1 2-2h' + (w - 4) + "a2 2 0 0 1 2 2v" + (st.headerH - 2) + "h-" + w + 'z" fill="' + C.header + '"/>');
     out.push('<text x="' + st.padX + '" y="' + n(st.headerH / 2 + st.headerSize * 0.36) + '" fill="' + C.headerText +
       '" font-family="' + FONT + '" font-size="' + st.headerSize + '">' + esc(t.name) + "</text>");
+    if (docMarks && t.doc) {
+      out.push(docMark(st.padX, st.headerH / 2 + st.headerSize * 0.36 + 3, t.nameW, "rgba(255,255,255,.7)"));
+    }
     g.cols.forEach(function (c, i) {
       var y = st.headerH + i * st.rowH, cy = y + st.rowH / 2, base = n(cy + st.rowSize * 0.36);
       var weight = c.pk || c.fk ? ' font-weight="bold"' : "";
@@ -81,6 +90,7 @@
       out.push('<rect class="rb" y="' + y + '" width="' + w + '" height="' + st.rowH + '" fill="' + C.body + '" fill-opacity="0"/>');
       out.push('<text x="' + st.padX + '" y="' + base + '" fill="' + color + '" font-family="' + FONT + '" font-size="' +
         st.rowSize + '"' + weight + ">" + esc(c.name) + "</text>");
+      if (docMarks && c.doc) out.push(docMark(st.padX, cy + st.rowSize * 0.36 + 2.5, c.nameW, color));
       var bx = st.padX + c.nameW + 6;
       c.badges.forEach(function (b) {
         var bh = st.badgeSize + 5;
@@ -89,7 +99,7 @@
           '" font-family="' + FONT + '" font-size="' + st.badgeSize + '">' + esc(b.t) + "</text>");
         bx += b.w + st.badgeGap;
       });
-      if (c.pk) out.push(keyIcon(w - st.padX - c.typeW - st.keyW + 1, cy));
+      if (c.pk) out.push(keyIcon(w - st.padX - c.typeW - st.keyW, cy));
       out.push('<text x="' + (w - st.padX) + '" y="' + base + '" text-anchor="end" fill="' + C.type + '" font-family="' + FONT +
         '" font-size="' + st.rowSize + '">' + esc(c.type) + "</text>");
       out.push("</g>");
@@ -164,9 +174,10 @@
     return model.rels.map(function (r) { return renderEdge(model, geo, pos, r); }).join("");
   }
 
-  function renderInner(model, pos, mode) {
-    var geo = geometry(model, mode);
-    var tables = model.tables.map(function (t) { return pos[t.id] ? renderTable(model, t, geo[t.id], pos[t.id]) : ""; }).join("");
+  /* 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 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>";
   }
 

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/src/quickdbd_cli/assets/style.css

@@ -53,6 +53,15 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .minimap svg { width: 100%; height: 100%; display: block; }
 .minimap .vpr { fill: rgba(43,87,151,.12); stroke: var(--blue); stroke-width: 1.5; vector-effect: non-scaling-stroke; }
 
+/* doc-comment tooltip */
+.tip { position: absolute; display: none; max-width: 340px; background: #23272b; color: #eee; border-radius: 6px;
+  padding: 8px 10px; font-size: 12px; line-height: 1.45; pointer-events: none; box-shadow: 0 4px 14px rgba(0,0,0,.25);
+  z-index: 5; }
+.tip.open { display: block; }
+.tip .tt { font-weight: bold; margin-bottom: 3px; }
+.tip .tt span { font-weight: normal; color: #9aa4ad; margin-left: 8px; }
+.tip .td { white-space: pre-wrap; color: #d8dde2; }
+
 .hint { position: absolute; left: 16px; bottom: 14px; color: var(--muted); font-size: 12px; }
 
 /* serve: editor pane */

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/src/quickdbd_cli/assets/viewer.js

@@ -24,7 +24,7 @@
 
   /* ------------------------------------------------------------- render */
   function render() {
-    vp.innerHTML = Q.renderInner(S.model, S.pos, S.mode);
+    vp.innerHTML = Q.renderInner(S.model, S.pos, S.mode, { docMarks: true });
     applyFocus();
     drawMinimap();
   }
@@ -124,7 +124,50 @@
       if (t) t.classList.add("hl");
     });
   });
-  vp.addEventListener("mouseleave", clearHover);
+  vp.addEventListener("mouseleave", function () { clearHover(); hideTip(); });
+
+  /* ------------------------------------------------------------- doc-comment tooltips */
+  var tip = document.getElementById("tip");
+  function hideTip() { tip.classList.remove("open"); }
+  function showTip(ev, title, sub, doc) {
+    tip.innerHTML = "";
+    var h = document.createElement("div");
+    h.className = "tt";
+    h.textContent = title;
+    if (sub) {
+      var s = document.createElement("span");
+      s.textContent = sub;
+      h.appendChild(s);
+    }
+    var d = document.createElement("div");
+    d.className = "td";
+    d.textContent = doc;
+    tip.appendChild(h);
+    tip.appendChild(d);
+    tip.classList.add("open");
+    moveTip(ev);
+  }
+  function moveTip(ev) {
+    var r = svg.getBoundingClientRect(), x = ev.clientX - r.left + 14, y = ev.clientY - r.top + 14;
+    var w = tip.offsetWidth, h = tip.offsetHeight;
+    if (x + w > r.width - 8) x = ev.clientX - r.left - w - 14;
+    if (y + h > r.height - 8) y = ev.clientY - r.top - h - 14;
+    tip.style.left = Math.max(8, x) + "px";
+    tip.style.top = Math.max(8, y) + "px";
+  }
+  vp.addEventListener("mousemove", function (ev) {
+    if (drag && drag.moved) { hideTip(); return; }
+    var tEl = ev.target.closest && ev.target.closest(".t");
+    if (!tEl) { hideTip(); return; }
+    var t = byId[tEl.getAttribute("data-id")], row = ev.target.closest(".r");
+    if (row) {
+      var cid = row.getAttribute("data-c"), c = t.cols.filter(function (x) { return x.id === cid; })[0];
+      if (c && c.doc) showTip(ev, t.name + "." + c.name, c.type, c.doc);
+      else hideTip();
+    } else if (t.doc && ev.target.closest(".th, text")) {
+      showTip(ev, t.name, t.aliases.length ? "as " + t.aliases.join(", ") : "", t.doc);
+    } else hideTip();
+  });
 
   /* ------------------------------------------------------------- pointer: pan, click, drag */
   var drag = null;

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.3}/src/quickdbd_cli/cli.py

@@ -103,6 +103,43 @@ def cmd_layout(args) -> int:
     return 0
 
 
+def cmd_import_dbt(args) -> int:
+    from .dbt import DbtImportError, import_dbt, write_result
+    from .parser import compile_sources
+
+    out = Path(args.output)
+    split = out.suffix != ".txt"
+    try:
+        result = import_dbt(
+            Path(args.manifest),
+            Path(args.catalog) if args.catalog else None,
+            packages=args.package,
+            select=args.select,
+            sources=not args.no_sources,
+            split=split,
+        )
+    except DbtImportError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    # Self-check: the generated text must compile cleanly.
+    schema = compile_sources([(name, text) for name, text in result.files.items()])
+    if schema.errors:
+        for d in schema.errors:
+            print(d.format(), file=sys.stderr)
+        print("error: generated schema did not compile (please report this as a bug)", file=sys.stderr)
+        return 1
+    written = write_result(result, out)
+    for s in result.skipped:
+        print(f"skipped: {s}", file=sys.stderr)
+    where = str(out) if not split else f"{out}/ ({len(written)} files)"
+    print(f"Wrote {where}: {result.tables} tables, {result.relationships} relationships")
+    if result.tables and not result.relationships:
+        print(
+            "hint: no relationships found; add `relationships` tests or foreign_key constraints in dbt", file=sys.stderr
+        )
+    return 0
+
+
 def cmd_serve(args) -> int:
     from .serve import serve
 
@@ -147,6 +184,28 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--layout")
     sp.set_defaults(func=cmd_layout)
 
+    sp = sub.add_parser("import", help="generate QuickDBD schema files from another source")
+    isub = sp.add_subparsers(dest="source", required=True)
+    dp = isub.add_parser(
+        "dbt",
+        help="from a dbt project's target/manifest.json",
+        description="Tables from models/seeds/snapshots/sources, relationships from `relationships` tests and "
+        "foreign_key constraints, types from catalog.json (run `dbt docs generate` first for types).",
+    )
+    dp.add_argument("manifest", help="path to manifest.json (or the target/ directory)")
+    dp.add_argument("-o", "--output", default="schema.txt", help="a .txt file, or a directory for one file per folder")
+    dp.add_argument("--catalog", help="catalog.json for column types (default: next to the manifest, if present)")
+    dp.add_argument(
+        "--package",
+        action="append",
+        help="dbt package(s) to include (default: the root project; 'all' for every package)",
+    )
+    dp.add_argument(
+        "--select", action="append", help="glob on model name, fqn (a.b.c) or file path, e.g. 'marts.*' (repeatable)"
+    )
+    dp.add_argument("--no-sources", action="store_true", help="leave out dbt sources")
+    dp.set_defaults(func=cmd_import_dbt)
+
     sp = sub.add_parser("serve", help="live editor: reload on save, drag tables to arrange")
     paths(sp)
     sp.add_argument("--port", type=int, default=8765)