quickdbd-cli 0.6.0__tar.gz → 0.6.1__tar.gz

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/NOTICE

@@ -25,6 +25,7 @@ The demo gallery (gallery/, not part of the Python package) includes schemas der
   Luis Rocha. MIT License.
 * dbt-synthea (gallery/synthea), OHDSI. Apache License 2.0. Trimmed dbt manifest and catalog only.
 * dbt_shopify (gallery/shopify), Fivetran. Apache License 2.0. Trimmed dbt manifest and catalog only.
+* qdbd-dbt-demo (gallery/skytrax), Minh (Mark) Pham. Apache License 2.0. Hand-written ERD and dbt yml only.
 
 Each folder keeps the upstream licence in its LICENSE file.
 

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.6.0
+Version: 0.6.1
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://qdbd.dev/
 Project-URL: Documentation, https://qdbd.dev/guide/
@@ -76,7 +76,7 @@ Description-Content-Type: text/markdown
   <a href="https://qdbd.dev/#demo"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/demo.gif" alt="Searching, focusing and opening a table in a qdbd diagram" width="760"></a>
 </p>
 <p align="center">
-  <em><a href="https://qdbd.dev/#demo">Watch the full 60-second demo →</a></em>
+  <em><a href="https://qdbd.dev/#demo">Watch the full 75-second demo →</a></em>
 </p>
 
 ## What is qdbd?
@@ -110,9 +110,9 @@ Every demo is a single HTML page written by `qdbd build`, from a QuickDBD schema
 | | |
 |---|---|
 | [![200 tables](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthetic.png)](https://qdbd.dev/demo/synthetic/)<br>**[200 tables](https://qdbd.dev/demo/synthetic/)**<br>Five business domains, 200 tables and every relationship type. Search, filter, click a table to focus it. | [![Schema diff](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/diff.png)](https://qdbd.dev/demo/diff/)<br>**[Schema diff](https://qdbd.dev/demo/diff/)**<br>What a branch changed, coloured in: new tables in green, changed columns in amber, removals listed. |
-| [![AdventureWorks](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/adventureworks.png)](https://qdbd.dev/demo/adventureworks/)<br>**[AdventureWorks](https://qdbd.dev/demo/adventureworks/)**<br>Microsoft's bicycle-company OLTP database: 68 tables in five schemas, one region each, with column descriptions. | [![OMOP CDM on Synthea](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthea.png)](https://qdbd.dev/demo/synthea/#t=concept)<br>**[OMOP CDM on Synthea](https://qdbd.dev/demo/synthea/#t=concept)**<br>OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests. |
+| [![OMOP CDM on Synthea](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthea.png)](https://qdbd.dev/demo/synthea/#t=concept)<br>**[OMOP CDM on Synthea](https://qdbd.dev/demo/synthea/#t=concept)**<br>OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests. | [![Skytrax reviews (dbt yml)](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/skytrax.png)](https://qdbd.dev/demo/skytrax/#t=dim_customer)<br>**[Skytrax reviews (dbt yml)](https://qdbd.dev/demo/skytrax/#t=dim_customer)**<br>Four star schemas, drawn by hand. One # @dbt: line adds the dbt yml's descriptions, pii tags and column types. Source: the qdbd-dbt-demo repo on GitHub. |
 
-[View all 19 demos →](https://qdbd.dev/demo/)
+[View all 21 demos →](https://qdbd.dev/demo/)
 <!-- gallery:end -->
 
 ## Quickstart
@@ -194,7 +194,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.6.0
+      - uses: MarkPhamm/quickdbd-cli@v0.6.1
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -278,7 +278,7 @@ You edit the text; the diagram is generated from it. Table positions are the one
 - [Install](https://qdbd.dev/install/) and [Quick Start](https://qdbd.dev/getting-started/)
 - [Schema Syntax](https://qdbd.dev/syntax/), [many files](https://qdbd.dev/files/), [table positions](https://qdbd.dev/layout/), [tags and colours](https://qdbd.dev/tags/)
 - [Reading the Diagram](https://qdbd.dev/reading-the-diagram/), [selectors](https://qdbd.dev/selectors/), [exports](https://qdbd.dev/exports/), [sharing a link](https://qdbd.dev/sharing/)
-- [dbt Projects](https://qdbd.dev/dbt/), with a [jaffle_shop walkthrough](https://qdbd.dev/example/)
+- [dbt Projects](https://qdbd.dev/dbt/), with a [jaffle_shop walkthrough](https://qdbd.dev/example/) and an [example dbt project](https://github.com/MarkPhamm/qdbd-dbt-demo) whose hand-drawn ERD takes its docs from the yml
 - [AI Agents (MCP)](https://qdbd.dev/mcp/): `qdbd mcp` for Claude, Copilot and Cursor
 - [Schema Diffs](https://qdbd.dev/diffs/), the [GitHub Action](https://qdbd.dev/github-action/) and the [CLI reference](https://qdbd.dev/cli/)
 - [Development](https://qdbd.dev/development/): working on qdbd itself, releasing, and adding a demo

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/README.md

@@ -37,7 +37,7 @@
   <a href="https://qdbd.dev/#demo"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/demo.gif" alt="Searching, focusing and opening a table in a qdbd diagram" width="760"></a>
 </p>
 <p align="center">
-  <em><a href="https://qdbd.dev/#demo">Watch the full 60-second demo →</a></em>
+  <em><a href="https://qdbd.dev/#demo">Watch the full 75-second demo →</a></em>
 </p>
 
 ## What is qdbd?
@@ -71,9 +71,9 @@ Every demo is a single HTML page written by `qdbd build`, from a QuickDBD schema
 | | |
 |---|---|
 | [![200 tables](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthetic.png)](https://qdbd.dev/demo/synthetic/)<br>**[200 tables](https://qdbd.dev/demo/synthetic/)**<br>Five business domains, 200 tables and every relationship type. Search, filter, click a table to focus it. | [![Schema diff](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/diff.png)](https://qdbd.dev/demo/diff/)<br>**[Schema diff](https://qdbd.dev/demo/diff/)**<br>What a branch changed, coloured in: new tables in green, changed columns in amber, removals listed. |
-| [![AdventureWorks](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/adventureworks.png)](https://qdbd.dev/demo/adventureworks/)<br>**[AdventureWorks](https://qdbd.dev/demo/adventureworks/)**<br>Microsoft's bicycle-company OLTP database: 68 tables in five schemas, one region each, with column descriptions. | [![OMOP CDM on Synthea](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthea.png)](https://qdbd.dev/demo/synthea/#t=concept)<br>**[OMOP CDM on Synthea](https://qdbd.dev/demo/synthea/#t=concept)**<br>OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests. |
+| [![OMOP CDM on Synthea](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/synthea.png)](https://qdbd.dev/demo/synthea/#t=concept)<br>**[OMOP CDM on Synthea](https://qdbd.dev/demo/synthea/#t=concept)**<br>OHDSI's dbt-synthea: synthetic patient records mapped to the OMOP Common Data Model. 145 tables, 235 relationships from tests. | [![Skytrax reviews (dbt yml)](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/gallery/skytrax.png)](https://qdbd.dev/demo/skytrax/#t=dim_customer)<br>**[Skytrax reviews (dbt yml)](https://qdbd.dev/demo/skytrax/#t=dim_customer)**<br>Four star schemas, drawn by hand. One # @dbt: line adds the dbt yml's descriptions, pii tags and column types. Source: the qdbd-dbt-demo repo on GitHub. |
 
-[View all 19 demos →](https://qdbd.dev/demo/)
+[View all 21 demos →](https://qdbd.dev/demo/)
 <!-- gallery:end -->
 
 ## Quickstart
@@ -155,7 +155,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.6.0
+      - uses: MarkPhamm/quickdbd-cli@v0.6.1
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -239,7 +239,7 @@ You edit the text; the diagram is generated from it. Table positions are the one
 - [Install](https://qdbd.dev/install/) and [Quick Start](https://qdbd.dev/getting-started/)
 - [Schema Syntax](https://qdbd.dev/syntax/), [many files](https://qdbd.dev/files/), [table positions](https://qdbd.dev/layout/), [tags and colours](https://qdbd.dev/tags/)
 - [Reading the Diagram](https://qdbd.dev/reading-the-diagram/), [selectors](https://qdbd.dev/selectors/), [exports](https://qdbd.dev/exports/), [sharing a link](https://qdbd.dev/sharing/)
-- [dbt Projects](https://qdbd.dev/dbt/), with a [jaffle_shop walkthrough](https://qdbd.dev/example/)
+- [dbt Projects](https://qdbd.dev/dbt/), with a [jaffle_shop walkthrough](https://qdbd.dev/example/) and an [example dbt project](https://github.com/MarkPhamm/qdbd-dbt-demo) whose hand-drawn ERD takes its docs from the yml
 - [AI Agents (MCP)](https://qdbd.dev/mcp/): `qdbd mcp` for Claude, Copilot and Cursor
 - [Schema Diffs](https://qdbd.dev/diffs/), the [GitHub Action](https://qdbd.dev/github-action/) and the [CLI reference](https://qdbd.dev/cli/)
 - [Development](https://qdbd.dev/development/): working on qdbd itself, releasing, and adding a demo

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/pyproject.toml

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

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

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/src/quickdbd_cli/assets/style.css

@@ -286,10 +286,10 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 /* doc-comment tooltip */
 .tip { position: absolute; display: none; max-width: 340px; background: var(--tip-bg); color: #eef0f2; border-radius: 8px;
   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; }
+  z-index: 5; overflow-wrap: anywhere; }
 .tip.open { display: block; }
 .tip .tt { font-weight: bold; margin-bottom: 3px; }
-.tip .tt span { font-weight: normal; color: #9aa4ad; margin-left: 8px; }
+.tip .tt span { font-weight: normal; color: #9aa4ad; margin-left: 8px; white-space: nowrap; }
 .tip .td { white-space: pre-wrap; color: #d8dde2; }
 
 .hint { position: absolute; left: 16px; bottom: 14px; color: var(--muted); font-size: 12px; }

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/src/quickdbd_cli/assets/viewer.js

@@ -193,7 +193,7 @@
   function fit(only, animate) {
     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
+    if (details.classList.contains("open")) sz = [Math.max(200, sz[0] - 400), sz[1]]; // the panel covers the right side
     // 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);

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/tests/test_convert.py

@@ -33,15 +33,19 @@ def _demo_sources() -> list[str]:
 @pytest.mark.parametrize("src", _demo_sources())
 def test_round_trip_examples_and_demos(src):
     sources = _sources(ROOT / src)
-    original = compile_sources([(d, t) for d, _, t in sources])
+    # dbt=False matches `qdbd convert`: a converted copy keeps `# @dbt:` as written and does not read the yml.
+    original = compile_sources([(d, t) for d, _, t in sources], dbt=False)
     to_dbml = conv.convert(sources, "dbml", split_groups=False)
     back = conv.convert([(k, k, v) for k, v in to_dbml.files.items()], "quickdbd", split_groups=False)
-    again = compile_sources(list(back.files.items()))
+    again = compile_sources(list(back.files.items()), dbt=False)
     assert again.errors == []
     lost = to_dbml.lost | back.lost
     assert conv.canonical(again, lost) == conv.canonical(original, lost)
     kinds = {w.message.split(":")[0] for w in to_dbml.warnings}
-    assert kinds <= {"table-level relationship", "alias", "settings"}, kinds
+    allowed = {"table-level relationship", "alias", "settings"}
+    if src in ("gallery/dbt-docs/schema.txt", "gallery/skytrax/erd"):
+        allowed.add("type")  # column types are left blank so the linked yml's data_type is what the diagram shows
+    assert kinds <= allowed, kinds
 
 
 def test_dbml_to_quickdbd_teammate_style():

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/tests/test_gallery.py

@@ -78,6 +78,21 @@ def test_feature_demos(built):
     assert _model(built / "regions" / "index.html").get("regions")
     tags = _model(built / "tags" / "index.html")
     assert {"dim", "fact", "staging", "gold"} <= {t["name"] for t in tags["tags"]}
+    docs = _model(built / "dbt-docs" / "index.html")
+    by_name = {t["name"]: t for t in docs["tables"]}
+    orders = by_name["orders"]
+    assert orders["doc"] == "One row per order, open or complete.\nRecognised in revenue once status is paid."
+    assert orders["tags"] == ["finance"]
+    status = next(c for c in orders["cols"] if c["name"] == "status")
+    assert status["type"] == "varchar(20)" and status["doc"] == "placed, paid, shipped or returned."
+    name = next(c for c in by_name["customers"]["cols"] if c["name"] == "name")
+    assert name["doc"] == "The name given at checkout."  # the schema comment and the yml say the same thing
+    email = next(c for c in by_name["customers"]["cols"] if c["name"] == "email")
+    assert email["tags"] == ["pii"] and email["type"] == "varchar"
+    assert by_name["shop.charges"]["tags"] == ["raw"]
+    refunds = by_name["planned_refunds"]
+    assert "tags" not in refunds  # `# @dbt: none`: nothing is read from the yml
+    assert refunds["doc"] == "Not in dbt yet: the refund flow is still being designed."
 
 
 def test_sample_databases_and_dbt_projects(built):
@@ -99,6 +114,10 @@ def test_sample_databases_and_dbt_projects(built):
     assert dw["regions"] and len({t["group"] for t in dw["tables"]}) == 5  # one region per business process
     aw = _model(built / "adventureworks" / "index.html")
     assert aw["regions"] and any(t.get("doc") for t in aw["tables"])  # MS_Description -> tooltips
+    sky = _model(built / "skytrax" / "index.html")
+    assert (len(sky["tables"]), len(sky["rels"])) == (13, 25)
+    cust = next(t for t in sky["tables"] if t["name"] == "dim_customer")
+    assert cust["doc"] and any(c.get("tags") == ["pii"] for c in cust["cols"])  # from the linked dbt yml
 
 
 def test_readme_gallery_is_in_sync():

quickdbd_cli-0.6.1/tests/test_gallery_hook.py

@@ -0,0 +1,30 @@
+"""The docs iframes load /demo/skytrax/ and /demo/jaffle/, which the mkdocs hook writes into the site."""
+
+import importlib.util
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+if not (ROOT / "hooks" / "gallery.py").exists() or not (ROOT / "gallery").exists():
+    pytest.skip("needs the git checkout's docs hook and gallery/", allow_module_level=True)
+
+_spec = importlib.util.spec_from_file_location("docs_gallery_hook", ROOT / "hooks" / "gallery.py")
+hook = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(hook)
+
+
+def test_docs_iframes_are_built_with_the_site(tmp_path):
+    hook.on_post_build({"site_dir": str(tmp_path)})
+    sky = tmp_path / "demo" / "skytrax" / "index.html"
+    jaffle = tmp_path / "demo" / "jaffle" / "index.html"
+    assert sky.exists() and jaffle.exists()
+    model = json.loads(re.search(r'id="qdbd-data">(.*?)</script>', sky.read_text(encoding="utf-8"), re.S).group(1))[
+        "model"
+    ]
+    cust = next(t for t in model["tables"] if t["name"] == "dim_customer")
+    assert cust["doc"]
+    assert any(c.get("tags") == ["pii"] for c in cust["cols"])
+    assert "orders" in jaffle.read_text(encoding="utf-8")

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/tests/test_home_hook.py

@@ -1,4 +1,4 @@
-"""The home-page MkDocs hook (hooks/home.py): the live mini diagram and the tour page."""
+"""The home-page MkDocs hook (hooks/home.py): the live mini diagram and the two tour pages."""
 
 import json
 import re
@@ -44,6 +44,13 @@ def test_mini_diagram_relationship_text():
     assert rel["card"]["sentence"] == "Each Customer row has many Order rows"
 
 
+def test_tour_has_a_dbt_chapter():
+    tour = re.search(r'<section class="qh-section qh-wrap qh-tour">(.*?)</section>', HOME_HTML, re.S).group(1)
+    assert tour.count("<li") == 5
+    assert 'data-page="dbt"' in tour
+    assert "data-dbt-src=" in tour
+
+
 def test_build_tour(tmp_path):
     page = home.build_tour(tmp_path)
     assert page.exists()
@@ -53,3 +60,15 @@ def test_build_tour(tmp_path):
     # the tables docs/javascripts/home-tour.js types, clicks and paths between
     driven = {"FactInternetSales", "DimCustomer", "FactResellerSales", "DimProductCategory"}
     assert driven <= {t["id"] for t in model["tables"]}
+
+
+def test_build_dbt_tour(tmp_path):
+    page = home.build_dbt_tour(tmp_path)
+    assert page.exists()
+    text = page.read_text(encoding="utf-8")
+    model = json.loads(re.search(r'id="qdbd-data">(.*?)</script>', text, re.S).group(1))["model"]
+    assert len(model["tables"]) == 7
+    orders = next(t for t in model["tables"] if t["id"] == "orders")
+    assert orders["doc"] == "One row per order, open or complete.\nRecognised in revenue once status is paid."
+    assert orders["tags"] == ["finance"]
+    assert {c["name"]: c["type"] for c in orders["cols"]}["amount"] == "numeric(12,2)"

{quickdbd_cli-0.6.0 → quickdbd_cli-0.6.1}/tests/test_viewer_contract.py

@@ -1,7 +1,8 @@
 """The page elements the qdbd.dev live demo drives (docs/javascripts/home-tour.js).
 
-The tour types into the search and filter boxes, clicks tree items, relationship lines and the card's Copy JOIN, and
-uses the path finder. Renaming any of these breaks the tour silently, so they are pinned here.
+The tour types into the search and filter boxes, clicks tree items, relationship lines and the card's Copy JOIN, uses
+the path finder, and in its dbt chapter highlights the yml description, tag chips and column docs. Renaming any of
+these breaks the tour silently, so they are pinned here.
 """
 
 from pathlib import Path
@@ -16,7 +17,16 @@ def test_tour_contract(tmp_path):
     out = tmp_path / "d.html"
     assert main(["build", str(ROOT / "examples" / "quickdbd-sample.txt"), "-o", str(out)]) == 0
     page = out.read_text(encoding="utf-8")
-    for el in ('id="q"', 'id="filter"', 'id="zfit"', 'id="rcard"'):
+    for el in ('id="q"', 'id="filter"', 'id="zfit"', 'id="rcard"', 'id="details"'):
         assert el in page, el
-    for el in ('id="pathto"', 'id="pathsql"', 'id="rcopy"', 'class="hit"', 'class="ti"'):
+    for el in (
+        'id="pathto"',
+        'id="pathsql"',
+        'id="rcopy"',
+        'class="hit"',
+        'class="ti"',
+        'class="doc"',
+        'class="cd"',
+        'class="tchip',
+    ):
         assert el in VIEWER, el

quickdbd_cli-0.6.0/src/quickdbd_cli/__init__.py

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