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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.1
+Version: 0.1.2
 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,6 +55,7 @@ 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.
@@ -157,7 +158,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.2}/README.md

@@ -30,6 +30,7 @@ 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.
@@ -132,7 +133,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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.1"
+version = "0.1.2"
 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.2}/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.2/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.2}/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;
@@ -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.2}/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.2}/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.2}/src/quickdbd_cli/html.py

@@ -50,6 +50,7 @@ BODY = """
     <div class="minimap">
       <svg id="mini" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet"></svg>
     </div>
+    <div class="tip" id="tip" role="tooltip"></div>
     <div class="hint">{hint}</div>
   </div>
 </div>

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.2}/src/quickdbd_cli/measure.py

@@ -60,7 +60,7 @@ def _column_json(col: Column) -> dict:
     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 {
+    out = {
         "id": col.id,
         "name": col.name,
         "type": col.type or "",
@@ -75,12 +75,16 @@ def _column_json(col: Column) -> dict:
         "typeW": type_w,
         "badges": bs,
     }
+    if col.comments:
+        out["doc"] = "\n".join(col.comments)
+    return out
 
 
 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"]
+    name_w = text_width(table.name, s["headerSize"])
+    w = name_w + 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"])
@@ -89,7 +93,10 @@ def table_json(table: Table) -> dict:
         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}
+    out = {"id": table.id, "name": table.name, "aliases": table.aliases, "w": w, "h": h, "nameW": name_w, "cols": cols}
+    if table.comments:
+        out["doc"] = "\n".join(table.comments)
+    return out
 
 
 def model_json(schema: Schema) -> dict:

{quickdbd_cli-0.1.1 → quickdbd_cli-0.1.2}/tests/test_pipeline.py

@@ -186,3 +186,34 @@ def test_missing_path(capsys):
 @pytest.mark.parametrize("bad_suffix", ["out.jpg"])
 def test_export_rejects_unknown_format(tmp_path, bad_suffix):
     assert main(["export", str(SAMPLE), "-o", str(tmp_path / bad_suffix)]) == 2
+
+
+DOCS = """# Customers who placed at least one order
+Customer # one row per person
+-
+CustomerId PK int
+# Contact address
+Email string # verified
+Name string
+"""
+
+
+def test_doc_comments_in_model():
+    m = model_json(compile_text(DOCS))
+    t = m["tables"][0]
+    assert t["doc"] == "Customers who placed at least one order\none row per person"
+    cols = {c["id"]: c for c in t["cols"]}
+    assert cols["Email"]["doc"] == "Contact address\nverified"
+    assert "doc" not in cols["Name"]
+
+
+def test_doc_marks_only_in_viewer_not_exports():
+    from quickdbd_cli.jsrt import runtime
+
+    m = model_json(compile_text(DOCS))
+    pos = {"Customer": [0, 0]}
+    rt = runtime()
+    rt.load("render.js")
+    viewer = rt.call("qdbd.renderInner", m, pos, "full", {"docMarks": True})
+    assert viewer.count('class="dm"') == 2  # table header + Email
+    assert 'class="dm"' not in export.render_svg(m, pos, embed_font=False)

quickdbd_cli-0.1.1/src/quickdbd_cli/__init__.py

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