quickdbd-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.7
+Version: 0.1.8
 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
@@ -202,7 +202,32 @@ Where the layout file goes:
 
 `qdbd build` never writes the layout file, so CI builds leave your working tree clean. More: [Table Positions](https://markphamm.github.io/quickdbd-cli/layout/).
 
-### 3.4 Differences from QuickDBD
+### 3.4 Tags and colours
+
+Give tables a role and a header colour. Tags are comments, so the file still pastes into QuickDBD.
+
+```text
+# @color gold #b8860b      # optional: pick a tag's colour
+
+# @tag: gold, pii
+customers
+-
+customer_id PK int
+
+dim_date                   # tagged "dim" automatically from its name
+-
+date_key PK int
+```
+
+A table's tags come from the first source that has any:
+
+1. an explicit `# @tag:` comment;
+2. its name: `dim_*` → dim, `fct_*` / `fact_*` → fact, `stg_*` → staging, `int_*` → intermediate, `raw_*` / `src_*` → raw;
+3. dbt tags, written as `# @dbt-tags:` by `qdbd import dbt`.
+
+The header takes the colour of the first tag. In the page, a chip per tag under the filter box shows only that tag, and the selector `tag:fact` works everywhere. More: [Tags and Colours](https://markphamm.github.io/quickdbd-cli/tags/).
+
+### 3.5 Differences from QuickDBD
 
 `qdbd` accepts a few things QuickDBD rejects, and prints a warning for each:
 
@@ -243,6 +268,7 @@ The explorer's filter box takes dbt-style selectors that follow **relationships*
 | `+orders+1` | one hop in both directions |
 | `group:marts`, `file:core.txt` | a folder or a file |
 | `col:customer_id` | tables with a matching column |
+| `tag:fact` | tables with a matching tag ([3.4](#34-tags-and-colours)) |
 | `a b` / `a,b` / `!a` | union / intersection / exclude |
 
 ```bash
@@ -288,6 +314,7 @@ See it on a real project: the [jaffle_shop demo](https://markphamm.github.io/qui
 | Relationships | `relationships` tests (incl. dbt_utils `relationships_where`) and `foreign_key` constraints |
 | Column types | `catalog.json` |
 | Tooltips | model and column descriptions |
+| Header colours | dbt `tags` (unless the name or an explicit `# @tag` says otherwise) |
 
 Useful options: `--select 'marts.*'` (repeatable), `--no-sources`, `--package all`, `-o schema.txt` for a single file.
 
@@ -341,7 +368,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.8
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -364,7 +391,7 @@ Run your dbt setup first, then let the action generate the schema:
 
 ```yaml
       # … dbt deps && dbt build && dbt docs generate
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.8
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -379,7 +406,7 @@ Commit `erd/` so pull requests can be compared with `main`. Set `dbt-check: true
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.7
+    rev: v0.1.8
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/README.md

@@ -174,7 +174,32 @@ Where the layout file goes:
 
 `qdbd build` never writes the layout file, so CI builds leave your working tree clean. More: [Table Positions](https://markphamm.github.io/quickdbd-cli/layout/).
 
-### 3.4 Differences from QuickDBD
+### 3.4 Tags and colours
+
+Give tables a role and a header colour. Tags are comments, so the file still pastes into QuickDBD.
+
+```text
+# @color gold #b8860b      # optional: pick a tag's colour
+
+# @tag: gold, pii
+customers
+-
+customer_id PK int
+
+dim_date                   # tagged "dim" automatically from its name
+-
+date_key PK int
+```
+
+A table's tags come from the first source that has any:
+
+1. an explicit `# @tag:` comment;
+2. its name: `dim_*` → dim, `fct_*` / `fact_*` → fact, `stg_*` → staging, `int_*` → intermediate, `raw_*` / `src_*` → raw;
+3. dbt tags, written as `# @dbt-tags:` by `qdbd import dbt`.
+
+The header takes the colour of the first tag. In the page, a chip per tag under the filter box shows only that tag, and the selector `tag:fact` works everywhere. More: [Tags and Colours](https://markphamm.github.io/quickdbd-cli/tags/).
+
+### 3.5 Differences from QuickDBD
 
 `qdbd` accepts a few things QuickDBD rejects, and prints a warning for each:
 
@@ -215,6 +240,7 @@ The explorer's filter box takes dbt-style selectors that follow **relationships*
 | `+orders+1` | one hop in both directions |
 | `group:marts`, `file:core.txt` | a folder or a file |
 | `col:customer_id` | tables with a matching column |
+| `tag:fact` | tables with a matching tag ([3.4](#34-tags-and-colours)) |
 | `a b` / `a,b` / `!a` | union / intersection / exclude |
 
 ```bash
@@ -260,6 +286,7 @@ See it on a real project: the [jaffle_shop demo](https://markphamm.github.io/qui
 | Relationships | `relationships` tests (incl. dbt_utils `relationships_where`) and `foreign_key` constraints |
 | Column types | `catalog.json` |
 | Tooltips | model and column descriptions |
+| Header colours | dbt `tags` (unless the name or an explicit `# @tag` says otherwise) |
 
 Useful options: `--select 'marts.*'` (repeatable), `--no-sources`, `--package all`, `-o schema.txt` for a single file.
 
@@ -313,7 +340,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.8
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -336,7 +363,7 @@ Run your dbt setup first, then let the action generate the schema:
 
 ```yaml
       # … dbt deps && dbt build && dbt docs generate
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.8
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -351,7 +378,7 @@ Commit `erd/` so pull requests can be compared with `main`. Set `dbt-check: true
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.7
+    rev: v0.1.8
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/pyproject.toml

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

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

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/assets/render.js

@@ -78,7 +78,7 @@
     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 + '"/>');
-    var state = t.diff && t.diff.state, hcol = state === "added" ? C.added : state === "changed" ? C.changed : C.header;
+    var state = t.diff && t.diff.state, hcol = state === "added" ? C.added : state === "changed" ? C.changed : t.color || C.header;
     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="' + hcol + '"/>');
     if (state) {
       out.push('<text x="' + (w - st.padX) + '" y="' + n(st.headerH / 2 + 4) + '" text-anchor="end" fill="#fff" font-family="' + FONT +
@@ -310,7 +310,7 @@
       cells.push(cell({
         id: tid, value: t.name, vertex: "1", parent: "1",
         style: "shape=table;startSize=" + HEADH + ";container=1;collapsible=1;childLayout=tableLayout;fixedRows=1;rowLines=0;" +
-          "fontStyle=1;align=left;spacingLeft=10;resizeLast=1;html=0;whiteSpace=wrap;fillColor=#2b5797;fontColor=#ffffff;" +
+          "fontStyle=1;align=left;spacingLeft=10;resizeLast=1;html=0;whiteSpace=wrap;fillColor=" + (t.color || C.header) + ";fontColor=#ffffff;" +
           "strokeColor=#dfe3e8;swimlaneFillColor=#ffffff;fontSize=14;",
       }, g(p[0] - b[0] + 40, p[1] - b[1] + 40, w, HEADH + Math.max(tg.cols.length, 0) * ROWH)));
       tg.cols.forEach(function (c, i) {
@@ -350,7 +350,7 @@
   /* ------------------------------------------------------------------ selectors (dbt-style, over relationships)
    * Space-separated atoms are unioned; a comma inside an atom intersects (a,b); a leading ! excludes.
    * Atom: [N]+  method:pattern  +[N]
-   *   method: name (default; also matches aliases), group, file, col
+   *   method: name (default; also matches aliases), group, file, col, tag
    *   pattern: glob with * and ?
    *   +x   x plus the tables it references (parents), any depth; 2+x limits to 2 hops
    *   x+   x plus the tables referencing it (children); x+1 limits to 1 hop
@@ -391,11 +391,12 @@
       else if (method === "group") ok = re.test(t.group || "") || (t.group || "").toLowerCase().indexOf(pat.toLowerCase() + "/") === 0;
       else if (method === "file") ok = re.test(t.file || "") || re.test((t.file || "").split("/").pop());
       else if (method === "col" || method === "column") ok = t.cols.some(function (c) { return re.test(c.name); });
+      else if (method === "tag") ok = (t.tags || []).some(function (x) { return re.test(x); });
       else if (method === "diff" || method === "state") {
         var ds = t.diff && t.diff.state, want = pat.toLowerCase();
         ok = !!ds && (want === "modified" || want === "*" || want === ds || (want === "new" && ds === "added"));
       }
-      else throw new Error("unknown selector method '" + method + "' (use name, group, file, col, diff)");
+      else throw new Error("unknown selector method '" + method + "' (use name, group, file, col, tag, diff)");
       if (ok) { out[t.id] = true; base.push(t.id); }
     });
     function hops(op, before) {

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/assets/style.css

@@ -56,6 +56,17 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .fstat { font-size: 11px; color: var(--muted); padding: 3px 2px 0; min-height: 14px; }
 .fstat.bad { color: #c0392b; }
 .fstat a { color: var(--blue); cursor: pointer; margin-left: 6px; }
+.tagbar { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px 0 2px; }
+.tchip { display: inline-flex; align-items: center; gap: 4px; font: 11px/1.6 inherit; padding: 0 7px 0 5px; border: 1px solid var(--line);
+  border-radius: 10px; background: #fff; color: var(--text, #333); cursor: pointer; }
+.tchip i { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
+.tchip small { color: var(--muted); }
+.tchip:hover { border-color: #b8c2d0; }
+.tchip.on { border-color: var(--blue); background: #eef3fa; }
+.tdot { display: inline-block; width: 7px; height: 7px; border-radius: 50%; margin: 0 6px 1px -13px; vertical-align: middle; }
+.tree.flat .tdot { margin-left: 0; }
+.details .ttags { margin: -4px 0 10px; display: flex; gap: 4px; flex-wrap: wrap; }
+.details .ttag { color: #fff; font-size: 11px; padding: 1px 8px; border-radius: 10px; cursor: pointer; text-decoration: none; }
 .tree { overflow: auto; padding: 4px 0 8px; }
 .explorer.collapsed .tree { display: none; }
 .gh { padding: 6px 12px 4px; font-size: 11px; font-weight: bold; color: var(--muted); text-transform: uppercase;

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/assets/viewer.js

@@ -331,7 +331,8 @@
       var open = q || !shut[g];
       var rows = items.map(function (t) {
         if (open) visible.push(t.id);
-        return '<div class="ti" data-id="' + Q.esc(t.id) + '">' + Q.esc(t.name) +
+        return '<div class="ti" data-id="' + Q.esc(t.id) + '">' +
+          (t.color ? '<i class="tdot" style="background:' + Q.esc(t.color) + '" title="' + Q.esc(t.tags.join(", ")) + '"></i>' : "") + Q.esc(t.name) +
           (t.aliases.length ? "<small>as " + Q.esc(t.aliases.join(", ")) + "</small>" : "") + "</div>";
       }).join("");
       if (flat) return rows;
@@ -408,7 +409,25 @@
     if (err) fstat.textContent = err;
     else if (ids) fstat.innerHTML = "Showing " + ids.length + " of " + S.model.tables.length + ' tables<a id="fclear">clear</a>';
     else fstat.textContent = "";
+    drawTags();
+  }
+  /* Tag legend: one chip per tag (header colour + count); a click filters to tag:NAME, a second click clears. */
+  var tagbar = document.getElementById("tagbar");
+  function drawTags() {
+    var tags = S.model.tags || [];
+    tagbar.style.display = tags.length ? "" : "none";
+    tagbar.innerHTML = tags.map(function (g) {
+      var on = S.filter.toLowerCase() === "tag:" + g.name;
+      return '<button class="tchip' + (on ? " on" : "") + '" data-tag="' + Q.esc(g.name) + '" title="Show only tag:' + Q.esc(g.name) +
+        '"><i style="background:' + Q.esc(g.color) + '"></i>' + Q.esc(g.name) + "<small>" + g.count + "</small></button>";
+    }).join("");
   }
+  tagbar.addEventListener("click", function (ev) {
+    var b = ev.target.closest(".tchip");
+    if (!b) return;
+    var expr = "tag:" + b.getAttribute("data-tag");
+    applyFilter(S.filter.toLowerCase() === expr ? "" : expr);
+  });
   function applyFilter(expr, keepView) {
     S.filter = (expr || "").trim();
     if (finput.value.trim() !== S.filter) finput.value = S.filter;
@@ -476,6 +495,12 @@
     if (t.aliases.length) meta.push("as " + Q.esc(t.aliases.join(", ")));
     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.tags) {
+      out.push('<div class="ttags">' + t.tags.map(function (g) {
+        var c = (S.model.tags || []).filter(function (x) { return x.name === g; })[0];
+        return '<a class="ttag" data-tag="' + Q.esc(g) + '" style="background:' + Q.esc(c ? c.color : "#2b5797") + '">' + Q.esc(g) + "</a>";
+      }).join("") + "</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">' +
@@ -558,6 +583,8 @@
   dbody.addEventListener("click", function (ev) {
     var a = ev.target.closest("a[data-go]");
     if (a) select(a.getAttribute("data-go"), { center: true });
+    var tg = ev.target.closest("a.ttag");
+    if (tg) applyFilter("tag:" + tg.getAttribute("data-tag"));
   });
   document.getElementById("dclose").onclick = function () { select(null); };
 
@@ -570,7 +597,7 @@
     var geo = Q.geometry(S.vm, S.mode), parts = [];
     S.vm.tables.forEach(function (t) {
       var p = S.pos[t.id];
-      if (p) parts.push('<rect x="' + p[0] + '" y="' + p[1] + '" width="' + geo[t.id].w + '" height="' + geo[t.id].h + '" fill="#2b5797" opacity=".55"/>');
+      if (p) parts.push('<rect x="' + p[0] + '" y="' + p[1] + '" width="' + geo[t.id].w + '" height="' + geo[t.id].h + '" fill="' + (t.color || "#2b5797") + '" opacity=".55"/>');
     });
     parts.push('<rect class="vpr" id="vpr"/>');
     mini.innerHTML = parts.join("");

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/dbt.py

@@ -113,6 +113,7 @@ class Tbl:
     group: str
     description: str = ""
     cols: dict[str, Col] = field(default_factory=dict)
+    tags: list[str] = field(default_factory=list)
 
     def col(self, name: str) -> Col:
         key = name.lower()
@@ -173,6 +174,17 @@ def _comment_lines(text: str) -> list[str]:
     return out
 
 
+def _node_tags(n: dict) -> list[str]:
+    """dbt tags (node-level and config), lowercased, in order, usable as qdbd tag names."""
+    out: list[str] = []
+    raw = list(n.get("tags") or []) + list((n.get("config") or {}).get("tags") or [])
+    for tag in raw:
+        tag = re.sub(r"[^a-z0-9_.-]+", "-", str(tag).lower()).strip("-.")
+        if tag and tag not in out:
+            out.append(tag)
+    return out
+
+
 class _Importer:
     def __init__(
         self,
@@ -231,7 +243,7 @@ class _Importer:
             name = self._base_name(n)
             if names[name] > 1:  # same name in two packages
                 name = f"{n.get('package_name')}.{name}"
-            t = Tbl(n["unique_id"], name, self._group(n), n.get("description") or "")
+            t = Tbl(n["unique_id"], name, self._group(n), n.get("description") or "", tags=_node_tags(n))
             self._columns(t, n)
             self.tables[t.uid] = t
             self.by_name.setdefault(n.get("name", "").lower(), []).append(t.uid)
@@ -435,6 +447,8 @@ class _Importer:
     # -- output -------------------------------------------------------------
     def render_table(self, t: Tbl) -> list[str]:
         lines = _comment_lines(t.description)
+        if t.tags:
+            lines.append(f"# @dbt-tags: {', '.join(t.tags)}")
         lines += [quote(t.name), "-"]
         for c in sorted(t.cols.values(), key=lambda c: (c.order, c.name.lower())):
             lines += _comment_lines(c.description)

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/html.py

@@ -37,6 +37,7 @@ BODY = """
         <input id="filter" type="text" placeholder="Filter: orders+1  group:marts  !stg_*" autocomplete="off"
           spellcheck="false" title="{filter_help}">
         <div class="fstat" id="fstat"></div>
+        <div class="tagbar" id="tagbar"></div>
       </div>
       <div id="tree" class="tree"></div>
     </div>
@@ -87,7 +88,7 @@ SIDE = """
 
 FILTER_HELP = (
     "dbt-style selectors. +x: x and what it references. x+: x and what references it. "
-    "N+x+N: hops. group:/file:/col: methods. a,b: both. !x: exclude."
+    "N+x+N: hops. group:/file:/col:/tag: methods. a,b: both. !x: exclude."
 )
 
 

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/measure.py

@@ -11,6 +11,7 @@ from functools import cache
 from importlib import resources
 from pathlib import PurePosixPath
 
+from . import tags
 from .model import Column, Schema, Table
 
 STYLE = {
@@ -127,12 +128,17 @@ def model_json(schema: Schema) -> dict:
                 "b": {"t": r.b.table, "c": r.b.column, "card": r.b.card},
             }
         )
-    return {
+    tables = [
+        {**table_json(t), "group": groups[t.path], "file": t.path, "line": t.line} for t in schema.tables.values()
+    ]
+    legend = tags.annotate(schema, tables)
+    out = {
         "style": STYLE,
-        "tables": [
-            {**table_json(t), "group": groups[t.path], "file": t.path, "line": t.line} for t in schema.tables.values()
-        ],
+        "tables": tables,
         "rels": rels,
         "zoom": schema.zoom,
         "position": list(schema.position) if schema.position else None,
     }
+    if legend:
+        out["tags"] = legend
+    return out

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/model.py

@@ -58,6 +58,8 @@ class Table:
     aliases: list[str] = field(default_factory=list)
     columns: dict[str, Column] = field(default_factory=dict)
     comments: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)  # `# @tag: ...` comments
+    dbt_tags: list[str] = field(default_factory=list)  # `# @dbt-tags: ...`, written by `qdbd import dbt`
 
 
 @dataclass
@@ -84,6 +86,7 @@ class Schema:
     layout: dict[str, tuple[float, float]] = field(default_factory=dict)
     diagnostics: list[Diagnostic] = field(default_factory=list)
     general_comments: list[str] = field(default_factory=list)
+    tag_colors: dict[str, str] = field(default_factory=dict)  # `# @color TAG #hex`
 
     @property
     def errors(self) -> list[Diagnostic]:

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/src/quickdbd_cli/parser.py

@@ -22,6 +22,21 @@ SECTION_ALIASES = {"rels": "relationships"}
 ALLOWED_REL = ", ".join(REL_TYPES)
 REJECT = "QuickDBD would reject this: "
 
+# qdbd directives live in comments, so files stay valid QuickDBD.
+TAG_RE = re.compile(r"^@(tags?|dbt-tags?)\s*:?\s*(.*)$", re.I)
+COLOR_RE = re.compile(r"^@colou?r\b\s*:?\s*(.*)$", re.I)
+TAG_NAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+HEX_RE = re.compile(r"^#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$")
+
+
+def split_tags(text: str) -> list[str]:
+    out: list[str] = []
+    for t in re.split(r"[\s,]+", text.strip()):
+        t = t.lower()
+        if t and t not in out:
+            out.append(t)
+    return out
+
 
 # --------------------------------------------------------------------------- helpers
 
@@ -197,6 +212,7 @@ class FileParse:
     layout_entries: list[Entry] = field(default_factory=list)
     diagnostics: list[Diagnostic] = field(default_factory=list)
     general_comments: list[str] = field(default_factory=list)
+    colors: dict[str, tuple[str, int]] = field(default_factory=dict)  # tag -> (#hex, line)
 
     def error(self, line: int, msg: str) -> None:
         self.diagnostics.append(Diagnostic(self.path, line, msg, "error"))
@@ -227,6 +243,11 @@ class _FileParser:
                 raw = raw.replace("\t", " ")
             blank = raw.rstrip() == ""
             data, comment = line_data(raw)
+            if comment and COLOR_RE.match(comment):
+                # the hex value has its own '#', which line_data treats as the end of the comment
+                full = re.search(r"#\s*(@colou?r\b.*)$", raw, re.I)
+                self._color(full.group(1).strip() if full else comment, lineno)
+                comment = None
             if comment:
                 pending.append(comment)
             elif blank and not seen_data:
@@ -250,6 +271,17 @@ class _FileParser:
                 out[section].append(entry)
         return out
 
+    def _color(self, comment: str, line: int) -> None:
+        parts = COLOR_RE.match(comment).group(1).split()
+        if len(parts) > 2 and parts[2].startswith("#"):  # a trailing comment after the colour
+            parts = parts[:2]
+        if len(parts) != 2 or not TAG_NAME_RE.match(parts[0]) or not HEX_RE.match(parts[1]):
+            self.fp.diagnostics.append(
+                Diagnostic(self.fp.path, line, "Invalid @color directive (use '# @color TAG #rrggbb')", "warning")
+            )
+            return
+        self.fp.colors[parts[0].lower()] = (parts[1].lower(), line)
+
     def _validate_section(self, name: str, seen: list[str], line: int) -> bool:
         if name not in SECTIONS:
             self.fp.error(line, f"Invalid section name '[{name}]' (allowed: {', '.join(SECTIONS)})")
@@ -369,7 +401,16 @@ class _FileParser:
             if ident in fp.tables:
                 fp.error(e.line, f"Table '{caption}' already defined")
                 return None
-            fp.tables[ident] = Table(ident, caption, fp.path, e.line, aliases, {}, list(e.comments))
+            table = Table(ident, caption, fp.path, e.line, aliases, {})
+            for c in e.comments:
+                m = TAG_RE.match(c)
+                if not m:
+                    table.comments.append(c)
+                elif m.group(1).lower().startswith("dbt"):
+                    table.dbt_tags += [t for t in split_tags(m.group(2)) if t not in table.dbt_tags]
+                else:
+                    table.tags += [t for t in split_tags(m.group(2)) if t not in table.tags]
+            fp.tables[ident] = table
             for a in aliases:
                 fp.aliases[a] = ident
             return ident
@@ -569,6 +610,12 @@ class _Resolver:
                 s.tables[ident] = table
             self.aliases.update(f.aliases)
             s.general_comments.extend(f.general_comments)
+            for tag, (color, line) in sorted(f.colors.items()):
+                if tag not in s.tag_colors:
+                    s.tag_colors[tag] = color
+                elif s.tag_colors[tag] != color:
+                    msg = f"@color for '{tag}' differs from an earlier file; using the first"
+                    self.error(f.path, line, msg, "warning")
             zoom = f.settings.get("zoom")
             pos = f.settings.get("position")
             lines = f.settings.get("_lines", {})

quickdbd_cli-0.1.8/src/quickdbd_cli/tags.py

@@ -0,0 +1,95 @@
+"""Table tags and their header colours.
+
+A table's tags come from the first source that has any:
+
+1. explicit ``# @tag: dim, pii`` comments;
+2. its name: ``dim_*`` / ``DimCustomer`` -> dim, ``fct_*`` -> fact, ``stg_*`` -> staging, ...;
+3. ``# @dbt-tags: ...`` comments written by ``qdbd import dbt``.
+
+The header takes the colour of the table's first tag. ``# @color TAG #hex`` overrides the defaults.
+"""
+
+from __future__ import annotations
+
+from .model import Schema, Table
+
+# tag -> name prefixes (matched as `prefix_...` or `PrefixName`)
+NAME_TAGS: list[tuple[str, tuple[str, ...]]] = [
+    ("dim", ("dim",)),
+    ("fact", ("fct", "fact")),
+    ("staging", ("stg", "staging")),
+    ("intermediate", ("int",)),
+    ("raw", ("raw", "src")),
+]
+
+# Defaults avoid the diff colours (green = added, amber = changed) and the untagged blue.
+DEFAULT_COLORS = {
+    "dim": "#00838f",
+    "fact": "#c2185b",
+    "staging": "#546e7a",
+    "intermediate": "#7b1fa2",
+    "raw": "#6d4c41",
+}
+PALETTE = ["#0277bd", "#4527a0", "#00695c", "#ad1457", "#827717", "#bf360c", "#37474f", "#283593", "#5d4037"]
+
+
+def _name_parts(name: str) -> list[str]:
+    """The name, plus the part after a source qualifier (`src.tbl`) or a dbt `<layer>_<source>__<entity>`."""
+    out = [name]
+    for sep in (".", "__"):
+        if sep in name:
+            out.append(name.rsplit(sep, 1)[1])
+    return out
+
+
+def name_tag(name: str) -> str | None:
+    for part in _name_parts(name):
+        low = part.lower()
+        for tag, prefixes in NAME_TAGS:
+            for p in prefixes:
+                if low.startswith(p + "_") and len(low) > len(p) + 1:
+                    return tag
+                rest = part[len(p) :]
+                if part[: len(p)] == p.capitalize() and rest[:1].isupper():
+                    return tag
+    return None
+
+
+def table_tags(t: Table) -> list[str]:
+    if t.tags:
+        return list(t.tags)
+    tag = name_tag(t.name)
+    if tag:
+        return [tag]
+    return list(t.dbt_tags)
+
+
+def tag_colors(schema: Schema, tags_by_table: dict[str, list[str]]) -> dict[str, str]:
+    """Colour of every tag in use: explicit @color, else the default, else the next palette colour (by name)."""
+    used = sorted({tag for tags in tags_by_table.values() for tag in tags})
+    out: dict[str, str] = {}
+    i = 0
+    for tag in used:
+        if tag in schema.tag_colors:
+            out[tag] = schema.tag_colors[tag]
+        elif tag in DEFAULT_COLORS:
+            out[tag] = DEFAULT_COLORS[tag]
+        else:
+            out[tag] = PALETTE[i % len(PALETTE)]
+            i += 1
+    return out
+
+
+def annotate(schema: Schema, tables: list[dict]) -> list[dict]:
+    """Add ``tags`` and ``color`` to each table dict of the model JSON; return the legend."""
+    by_id = {t["id"]: table_tags(schema.tables[t["id"]]) for t in tables}
+    colors = tag_colors(schema, by_id)
+    counts: dict[str, int] = {}
+    for t in tables:
+        tags = by_id[t["id"]]
+        if tags:
+            t["tags"] = tags
+            t["color"] = colors[tags[0]]
+            for tag in tags:
+                counts[tag] = counts.get(tag, 0) + 1
+    return [{"name": k, "color": colors[k], "count": counts[k]} for k in sorted(counts, key=lambda k: (-counts[k], k))]

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.8}/tests/test_select.py

@@ -93,7 +93,7 @@ def test_selectors(model, expr, expected):
 
 def test_unknown_method(model):
     with pytest.raises(Exception, match="unknown selector method"):
-        sel(model, "tag:pii")
+        sel(model, "owner:pii")
 
 
 # ------------------------------------------------------------------ CLI --select / --exclude
@@ -132,8 +132,8 @@ def test_select_errors(tmp_path, capsys):
     root = write_files(tmp_path)
     assert main(["build", str(root), "-s", "nope", "-o", str(tmp_path / "d.html")]) == 1
     assert "no tables match 'nope'" in capsys.readouterr().err
-    assert main(["build", str(root), "-s", "tag:x", "-o", str(tmp_path / "d.html")]) == 1
-    assert "error: unknown selector method 'tag'" in capsys.readouterr().err
+    assert main(["build", str(root), "-s", "owner:x", "-o", str(tmp_path / "d.html")]) == 1
+    assert "error: unknown selector method 'owner'" in capsys.readouterr().err
 
 
 def test_selector_expr():

quickdbd_cli-0.1.8/tests/test_tags.py

@@ -0,0 +1,196 @@
+"""Table tags (`# @tag`, name prefixes, `# @dbt-tags`) and their header colours."""
+
+import json
+
+import pytest
+
+from quickdbd_cli.dbt import import_dbt
+from quickdbd_cli.diff import annotate_model, diff_schemas
+from quickdbd_cli.export import render_drawio, render_svg
+from quickdbd_cli.jsrt import runtime
+from quickdbd_cli.measure import model_json
+from quickdbd_cli.parser import compile_sources, compile_text
+from quickdbd_cli.tags import DEFAULT_COLORS, PALETTE, name_tag
+
+SCHEMA = """# @color fact #123456
+dim_customer
+-
+id PK int
+
+# Orders, one per checkout
+# @tag: gold, PII
+fct_orders
+-
+id PK int
+customer_id int FK >- dim_customer.id
+
+Thing # @dbt-tags: nightly
+-
+id int
+
+stg_shop__payments # @dbt-tags: nightly
+-
+id int
+
+Plain
+-
+id int
+"""
+
+
+def tables(model):
+    return {t["name"]: t for t in model["tables"]}
+
+
+@pytest.fixture(scope="module")
+def model():
+    return model_json(compile_text(SCHEMA))
+
+
+def test_directives_are_parsed_and_kept_out_of_docs():
+    s = compile_text(SCHEMA)
+    t = s.tables["fct_orders"]
+    assert t.tags == ["gold", "pii"]
+    assert t.comments == ["Orders, one per checkout"]
+    assert s.tables["Thing"].dbt_tags == ["nightly"]
+    assert s.tables["Thing"].comments == []
+    assert s.tag_colors == {"fact": "#123456"}
+    assert s.diagnostics == []
+
+
+def test_precedence_explicit_then_name_then_dbt(model):
+    t = tables(model)
+    assert t["fct_orders"]["tags"] == ["gold", "pii"]  # explicit beats the fct_ prefix
+    assert t["dim_customer"]["tags"] == ["dim"]  # name
+    assert t["stg_shop__payments"]["tags"] == ["staging"]  # name beats dbt tags
+    assert t["Thing"]["tags"] == ["nightly"]  # dbt tags
+    assert "tags" not in t["Plain"] and "color" not in t["Plain"]
+
+
+def test_colours_and_legend(model):
+    t = tables(model)
+    assert t["dim_customer"]["color"] == DEFAULT_COLORS["dim"]
+    assert t["fct_orders"]["color"] == PALETTE[0]  # "gold": first non-default tag, by name
+    legend = {g["name"]: (g["color"], g["count"]) for g in model["tags"]}
+    assert legend == {
+        "dim": (DEFAULT_COLORS["dim"], 1),
+        "gold": (PALETTE[0], 1),
+        "nightly": (PALETTE[1], 1),
+        "pii": (PALETTE[2], 1),
+        "staging": (DEFAULT_COLORS["staging"], 1),
+    }
+    assert "fact" not in legend  # @color for an unused tag doesn't add it
+
+
+def test_color_with_trailing_comment():
+    s = compile_text("# @color gold #b8860b   # optional: pick a colour\nA\n-\nid int\n")
+    assert s.tag_colors == {"gold": "#b8860b"} and s.diagnostics == []
+
+
+def test_color_override():
+    m = model_json(compile_text("# @color dim #ABCDEF\ndim_x\n-\nid int\n"))
+    assert m["tables"][0]["color"] == "#abcdef"
+
+
+def test_no_tags_no_legend():
+    assert "tags" not in model_json(compile_text("A\n-\nid int\n"))
+
+
+@pytest.mark.parametrize(
+    "line",
+    ["# @color dim", "# @color dim red", "# @color #fff dim", "# @color dim #12345"],
+)
+def test_bad_color_is_a_warning(line):
+    s = compile_text(f"{line}\nA\n-\nid int\n")
+    assert [d.severity for d in s.diagnostics] == ["warning"]
+    assert "Invalid @color" in s.diagnostics[0].message
+
+
+def test_conflicting_colors_across_files():
+    a = ("a.txt", "# @color dim #111111\nA\n-\nid int\n")
+    b = ("b.txt", "# @color dim #222222\nB\n-\nid int\n")
+    s = compile_sources([a, b])
+    assert s.tag_colors == {"dim": "#111111"}
+    assert [(d.path, d.severity) for d in s.diagnostics] == [("b.txt", "warning")]
+
+
+@pytest.mark.parametrize(
+    "name,tag",
+    [
+        ("dim_customer", "dim"),
+        ("DimCustomer", "dim"),
+        ("Dimension", None),
+        ("fct_orders", "fact"),
+        ("fact_sales", "fact"),
+        ("FactSales", "fact"),
+        ("Factory", None),
+        ("stg_orders", "staging"),
+        ("stg_shop__orders", "staging"),
+        ("conformed__dim_airline", "dim"),
+        ("int_orders_pivoted", "intermediate"),
+        ("integer_table", None),
+        ("raw_orders", "raw"),
+        ("jaffle_shop.raw_orders", "raw"),
+        ("dim_", None),
+        ("Customer", None),
+    ],
+)
+def test_name_tags(name, tag):
+    assert name_tag(name) == tag
+
+
+def test_tag_selector(model):
+    rt = runtime()
+    rt.load("render.js")
+    assert rt.call("qdbdSelect", model, "tag:dim") == ["dim_customer"]
+    assert rt.call("qdbdSelect", model, "tag:pii") == ["fct_orders"]
+    assert rt.call("qdbdSelect", model, "tag:dim+") == ["dim_customer", "fct_orders"]
+    assert rt.call("qdbdSelect", model, "tag:nope") == []
+
+
+def test_svg_and_drawio_use_the_tag_colour(model):
+    pos = {t["id"]: [i * 300, 0] for i, t in enumerate(model["tables"])}
+    svg = render_svg(model, pos, embed_font=False)
+    assert DEFAULT_COLORS["dim"] in svg and PALETTE[0] in svg and "#2b5797" in svg  # Plain stays blue
+    xml = render_drawio(model, pos)
+    assert "fillColor=" + DEFAULT_COLORS["dim"] in xml
+
+
+def test_diff_colour_wins_over_tag():
+    old = compile_text("A\n-\nid int\n")
+    new = compile_text("A\n-\nid int\n\ndim_b\n-\nid int\n")
+    m = annotate_model(model_json(new), diff_schemas(old, new), "main")
+    b = next(t for t in m["tables"] if t["name"] == "dim_b")
+    svg = render_svg(m, {"A": [0, 0], "dim_b": [300, 0]}, only=["dim_b"], embed_font=False)
+    assert b["color"] == DEFAULT_COLORS["dim"] and "#2e7d32" in svg and DEFAULT_COLORS["dim"] not in svg
+
+
+def test_dbt_import_writes_dbt_tags(tmp_path):
+    def node(uid, name, tags=None, config_tags=None):
+        return {
+            "unique_id": uid,
+            "resource_type": "model",
+            "name": name,
+            "package_name": "shop",
+            "fqn": ["shop", name],
+            "original_file_path": f"models/{name}.sql",
+            "description": "",
+            "columns": {"id": {"name": "id", "description": "", "data_type": "int"}},
+            "tags": tags or [],
+            "config": {"tags": config_tags or []},
+        }
+
+    nodes = {
+        "model.shop.orders": node("model.shop.orders", "orders", ["Nightly", "finance"], ["finance"]),
+        "model.shop.dim_users": node("model.shop.dim_users", "dim_users", ["nightly"]),
+        "model.shop.misc": node("model.shop.misc", "misc"),
+    }
+    mf = tmp_path / "manifest.json"
+    mf.write_text(json.dumps({"metadata": {"project_name": "shop"}, "nodes": nodes, "sources": {}}))
+    res = import_dbt(mf)
+    text = "".join(res.files.values())
+    assert "# @dbt-tags: nightly, finance\norders\n" in text
+    m = tables(model_json(compile_sources(list(res.files.items()))))
+    assert m["orders"]["tags"] == ["nightly", "finance"]
+    assert m["dim_users"]["tags"] == ["dim"]  # name beats dbt tags
+    assert "tags" not in m["misc"]

quickdbd_cli-0.1.7/src/quickdbd_cli/__init__.py

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