quickdbd-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.3.0
+Version: 0.3.1
 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

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/pyproject.toml

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

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

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/agent.py

@@ -471,6 +471,8 @@ def describe_tables(ws: Workspace, args: dict) -> Result:
                 flags.append("auto")
             if col["default"] is not None:
                 flags.append(f"default={col['default']}")
+            if col.get("tags"):
+                flags.append(f"tags {', '.join(col['tags'])}")
             if col["type"] in enums:
                 vals = enums[col["type"]]
                 flags.append("enum(" + ", ".join(vals[:20]) + (", …" if len(vals) > 20 else "") + ")")

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/assets/render.js

@@ -52,14 +52,14 @@
     return set;
   }
 
-  /* Visible columns of each table for a collapse mode: "full" | "keys" | "header". */
+  /* Visible columns of each table for a collapse mode: "full" | "keys" | "header". Tagged columns count as keys. */
   function geometry(model, mode) {
     var st = model.style, rel = mode === "keys" ? relatedColumns(model) : null, out = {};
     model.tables.forEach(function (t) {
       var cols = [];
       if (mode !== "header") {
         t.cols.forEach(function (c) {
-          if (mode === "full" || c.pk || c.fk || rel[t.id + "\u0000" + c.id]) cols.push(c);
+          if (mode === "full" || c.pk || c.fk || c.color || rel[t.id + "\u0000" + c.id]) cols.push(c);
         });
       }
       var rows = {};
@@ -105,14 +105,22 @@
     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"' : "";
-      var color = c.pk ? C.pk : c.fk ? C.fk : C.text, rn = c.pk ? "rn rpk" : c.fk ? "rn rfk" : "rn";
+      var color = c.color || (c.pk ? C.pk : c.fk ? C.fk : C.text), rn = c.pk ? "rn rpk" : c.fk ? "rn rfk" : "rn";
       out.push('<g class="r" data-c="' + esc(c.id) + '">');
+      // a tagged column: tinted row and a bar in the tag colour (a diff bar, drawn next, covers the bar)
+      if (c.color) {
+        out.push('<rect y="' + y + '" width="' + w + '" height="' + st.rowH + '" fill="' + c.color + '" fill-opacity=".1"/>');
+        out.push('<rect y="' + (y + 3) + '" width="3" height="' + (st.rowH - 6) + '" fill="' + c.color + '"/>');
+      }
       out.push('<rect class="rb" y="' + y + '" width="' + w + '" height="' + st.rowH + '" fill="' + C.body + '" fill-opacity="0"/>');
       var cstate = t.diff && t.diff.cols && t.diff.cols[c.id];
       if (cstate) out.push('<rect y="' + (y + 3) + '" width="3" height="' + (st.rowH - 6) + '" fill="' + C[cstate] + '"/>');
-      out.push('<text class="' + rn + '" x="' + st.padX + '" y="' + base + '" fill="' + color + '" font-family="' + FONT + '" font-size="' +
-        st.rowSize + '"' + weight + ">" + esc(c.name) + "</text>");
+      out.push('<text class="' + rn + '" x="' + st.padX + '" y="' + base + '" fill="' + color + '"' + (c.color ? ' style="fill:' + c.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));
+      if (c.tags && c.tags.indexOf("removed") >= 0) {
+        out.push('<line x1="' + st.padX + '" y1="' + n(cy) + '" x2="' + n(st.padX + c.nameW) + '" y2="' + n(cy) + '" stroke="' + color + '" stroke-width="1.2"/>');
+      }
       var bx = st.padX + c.nameW + 6;
       c.badges.forEach(function (b) {
         var bh = st.badgeSize + 5;
@@ -337,11 +345,12 @@
         }, g(0, HEADH + i * ROWH, w, ROWH)));
         var base = "shape=partialRectangle;connectable=0;fillColor=none;top=0;left=0;bottom=0;right=0;overflow=hidden;html=0;";
         var flags = c.badges.map(function (x) { return x.t; }).join(" ");
+        var fs = (c.pk ? 5 : c.fk ? 1 : 0) | (c.tags && c.tags.indexOf("removed") >= 0 ? 8 : 0); // bold, underline, strike
         cells.push(cell({ id: id(), value: key, vertex: "1", parent: rid, style: base + "fontStyle=1;fontColor=#2b5797;align=center;fontSize=11;" },
           g(0, 0, KEYW, ROWH)));
         cells.push(cell({
           id: id(), value: c.name + (flags ? "  [" + flags + "]" : "") + (c.type ? " : " + c.type : ""), vertex: "1", parent: rid,
-          style: base + "align=left;spacingLeft=6;fontSize=12;" + (c.pk ? "fontStyle=5;" : c.fk ? "fontStyle=1;" : ""),
+          style: base + "align=left;spacingLeft=6;fontSize=12;" + (fs ? "fontStyle=" + fs + ";" : "") + (c.color ? "fontColor=" + c.color + ";" : ""),
         }, g(KEYW, 0, w - KEYW, ROWH)));
       });
     });
@@ -407,7 +416,10 @@
       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 === "tag") {
+        var has = function (x) { return re.test(x); };
+        ok = (t.tags || []).some(has) || t.cols.some(function (c) { return (c.tags || []).some(has); });
+      }
       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"));

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/assets/syntax-reference.md

@@ -78,6 +78,7 @@ Declare a relationship once, in either direction.
 - `#` starts a comment, except inside double quotes. Comment lines directly above a table or column, plus a comment at the end of its line, become its documentation.
 - Tags give tables a role and a header colour: `# @tag: gold, pii` above a table. Names like `dim_`, `fct_`, `stg_`, `int_`, `raw_` are tagged automatically.
 - `# @color gold #b8860b` sets a tag's colour (anywhere in any file).
+- Columns take tags too, on or above the column line: `discount decimal # @tag: added`. The row is tinted in the tag's colour; `added` is green, `removed` is red and struck through. Use them to mark proposed column changes for review.
 
 ## Settings and layout sections
 

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/assets/viewer.js

@@ -552,6 +552,10 @@
       if (c.pk) tags.push('<span class="tag pk">PK</span>');
       if (c.fk) tags.push('<span class="tag fk">FK</span>');
       c.badges.forEach(function (b) { tags.push('<span class="tag">' + Q.esc(b.t) + "</span>"); });
+      (c.tags || []).forEach(function (g) {
+        var tc = (S.model.tags || []).filter(function (x) { return x.name === g; })[0];
+        tags.push('<a class="ttag" data-tag="' + Q.esc(g) + '" style="background:' + Q.esc(tc ? tc.color : "#2b5797") + '">' + Q.esc(g) + "</a>");
+      });
       out.push('<tr><td class="cn">' + Q.esc(c.name) + " " + tags.join("") + (c.doc ? '<div class="cd">' + Q.esc(c.doc) + "</div>" : "") +
         '</td><td class="ct">' + Q.esc(c.type) + "</td></tr>");
     });

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/convert.py

@@ -82,7 +82,7 @@ def canonical(schema: Schema, lost: set[tuple]) -> dict:
                 continue
             col = {
                 "type": c.type or "", "pk": c.pk, "unique": c.unique, "index": c.index, "nullable": c.nullable,
-                "identity": c.identity, "default": _norm_default(c.default), "doc": _doc(c.comments),
+                "identity": c.identity, "default": _norm_default(c.default), "doc": _doc(c.comments), "tags": c.tags,
             }  # fmt: skip
             for k in list(col):
                 if ("col", t.name, c.name, k) in lost:
@@ -202,7 +202,8 @@ class _DbmlWriter:
                 self.res.lost.add(("col", t.name, c.name, "type"))
                 typ = "unknown"
             typ = typ if _DBML_TYPE.fullmatch(typ) else _dbml_name(typ)
-            out.append(f"  {_dbml_name(c.name)} {typ}" + (f" [{', '.join(settings)}]" if settings else ""))
+            tags = f" // @tag: {', '.join(c.tags)}" if c.tags else ""
+            out.append(f"  {_dbml_name(c.name)} {typ}" + (f" [{', '.join(settings)}]" if settings else "") + tags)
         if indexed:
             out += ["", "  indexes {"] + [f"    {_dbml_name(n)}" for n in indexed] + ["  }"]
         if t.comments:
@@ -367,6 +368,8 @@ class _QuickdbdWriter:
                 self.res.lost.add(("col", t.name, c.name, "default"))
                 c = dataclasses.replace(c, default=None)
             out += [f"# {x}" for x in c.comments if x.strip()]
+            if c.tags:
+                out.append(f"# @tag: {', '.join(c.tags)}")
             out.append(_quickdbd_column(c, self.fks.get((t.id, c.id), [])))
         return out
 

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/dbml.py

@@ -1131,6 +1131,7 @@ class _Interpreter:
                     elif s.key == "note" and s.value and s.value[0].kind in ("str", "quoted"):
                         v = s.value[0]
                         col.comments = _doc_lines(_normalize_note(v.value) if v.multiline else v.value)
+                self._col_tags(col)
                 t.columns[col.id] = col
             for ix in indexes:
                 missing = [c for c in ix.columns if encode(c) not in t.columns]
@@ -1291,6 +1292,18 @@ class _Interpreter:
                 target[:0] = [x for x in split_tags(m.group(2)) if x not in target]
             line -= 1
 
+    def _col_tags(self, col: Column) -> None:
+        """`// @tag:` at the end of the column's line, or on comment lines right above it."""
+        lines = [col.line]
+        line = col.line - 1
+        while line in self.comments and line not in self.code_lines:
+            lines.append(line)
+            line -= 1
+        for line in reversed(lines):
+            m = TAG_RE.match(self.comments.get(line, ""))
+            if m and not m.group(1).lower().startswith("dbt"):
+                col.tags += [x for x in split_tags(m.group(2)) if x not in col.tags]
+
     def colors(self) -> None:
         first_code = min(self.code_lines, default=0)
         self.fp.general_comments = [

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/measure.py

@@ -79,6 +79,8 @@ def _column_json(col: Column) -> dict:
     }
     if col.comments:
         out["doc"] = "\n".join(col.comments)
+    if col.tags:
+        out["tags"] = list(col.tags)
     return out
 
 

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/model.py

@@ -47,6 +47,7 @@ class Column:
     default: str | None = None
     virtual: bool = False
     comments: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)  # `# @tag: ...` comments
 
 
 @dataclass

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/parser.py

@@ -475,7 +475,13 @@ class _FileParser:
         if is_virtual(ident):
             return Column(VIRTUAL_FIELD, "", e.line, virtual=True)
         tokens = [tokens[0]] + self._merge_paren_tokens(tokens[1:], e.line)
-        col = Column(ident, name, e.line, comments=list(e.comments))
+        col = Column(ident, name, e.line)
+        for c in e.comments:
+            m = TAG_RE.match(c)
+            if m and not m.group(1).lower().startswith("dbt"):
+                col.tags += [t for t in split_tags(m.group(2)) if t not in col.tags]
+            else:
+                col.comments.append(c)
         fk_at = -1
         d = 0
         while d + 1 < len(tokens):

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/src/quickdbd_cli/tags.py

@@ -8,10 +8,15 @@ A table's tags come from the first source that has any:
 
 The header takes the colour of the table's first tag. ``# @color TAG #hex`` overrides the defaults, and a DBML
 ``headercolor`` beats both.
+
+Columns take tags too (``# @tag: added`` on or above the column line), which mark the row in the first tag's colour;
+``added`` and ``removed`` default to green and red, for hand-marked proposed changes.
 """
 
 from __future__ import annotations
 
+from collections.abc import Iterable
+
 from .model import Schema, Table
 
 # tag -> name prefixes (matched as `prefix_...` or `PrefixName`)
@@ -23,13 +28,16 @@ NAME_TAGS: list[tuple[str, tuple[str, ...]]] = [
     ("raw", ("raw", "src")),
 ]
 
-# Defaults avoid the diff colours (green = added, amber = changed) and the untagged blue.
+# Table-role defaults avoid the diff colours (green = added, amber = changed) and the untagged blue; `added` and
+# `removed` are meant for columns, and use the diff green on purpose.
 DEFAULT_COLORS = {
     "dim": "#00838f",
     "fact": "#c2185b",
     "staging": "#546e7a",
     "intermediate": "#7b1fa2",
     "raw": "#6d4c41",
+    "added": "#2e7d32",
+    "removed": "#c62828",
 }
 PALETTE = ["#0277bd", "#4527a0", "#00695c", "#ad1457", "#827717", "#bf360c", "#37474f", "#283593", "#5d4037"]
 
@@ -65,9 +73,9 @@ def table_tags(t: Table) -> list[str]:
     return list(t.dbt_tags)
 
 
-def tag_colors(schema: Schema, tags_by_table: dict[str, list[str]]) -> dict[str, str]:
+def tag_colors(schema: Schema, tag_lists: Iterable[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})
+    used = sorted({tag for tags in tag_lists for tag in tags})
     out: dict[str, str] = {}
     i = 0
     for tag in used:
@@ -82,17 +90,22 @@ def tag_colors(schema: Schema, tags_by_table: dict[str, list[str]]) -> dict[str,
 
 
 def annotate(schema: Schema, tables: list[dict]) -> list[dict]:
-    """Add ``tags`` and ``color`` to each table dict of the model JSON; return the legend."""
+    """Add ``tags`` and ``color`` to each table dict of the model JSON, and ``color`` to tagged columns; return the
+    legend (count = tables carrying the tag, on the table or on a column)."""
     by_id = {t["id"]: table_tags(schema.tables[t["id"]]) for t in tables}
-    colors = tag_colors(schema, by_id)
+    col_tags = {t["id"]: [g for c in t["cols"] for g in c.get("tags", [])] for t in tables}
+    colors = tag_colors(schema, [*by_id.values(), *col_tags.values()])
     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
+        for c in t["cols"]:
+            if c.get("tags"):
+                c["color"] = colors[c["tags"][0]]
+        for tag in dict.fromkeys(tags + col_tags[t["id"]]):
+            counts[tag] = counts.get(tag, 0) + 1
         own = schema.tables[t["id"]].color  # DBML headercolor
         if own:
             t["color"] = own

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/tests/test_convert.py

@@ -146,6 +146,15 @@ def test_docs_and_tags_round_trip():
     assert t.columns["Id"].comments == ["the key"]
 
 
+def test_column_tags_round_trip():
+    text = "a\n-\nid PK int\nnew int # @tag: added\n# @tag: removed, pii\nold int\n"
+    dbml = conv.convert([("s.txt", "s.txt", text)], "dbml", split_groups=False).files["s.dbml"]
+    assert "  new int // @tag: added\n" in dbml
+    back = conv.convert([("s.dbml", "s.dbml", dbml)], "quickdbd", split_groups=False).files["s.txt"]
+    cols = compile_sources([("s.txt", back)]).tables["a"].columns
+    assert cols["new"].tags == ["added"] and cols["old"].tags == ["removed", "pii"]
+
+
 def test_already_in_target_syntax_is_copied():
     res = conv.convert([("t.dbml", "t.dbml", TEAM)], "dbml", split_groups=False)
     assert res.files == {"t.dbml": TEAM}

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/tests/test_dbml.py

@@ -269,6 +269,15 @@ Table a [headercolor: #0A0] {
     assert fp.colors["hot"][0] == "#ff0000"
 
 
+def test_column_tags_from_comments():
+    text = "Table a {\n  id int // @tag: added\n  // @tag: removed\n  // @dbt-tags: x\n  old int [note: 'gone']\n}\n"
+    _, schema = compile_dbml(text)
+    assert errors(schema) == []
+    cols = schema.tables["a"].columns
+    assert cols["id"].tags == ["added"]
+    assert cols["old"].tags == ["removed"] and cols["old"].comments == ["gone"]
+
+
 def test_optional_relationship_operators():
     text = "Table a {\n  id int [pk]\n}\nTable b {\n  a_id int\n}\nRef: b.a_id >? a.id\n"
     _, schema = compile_dbml(text)

{quickdbd_cli-0.3.0 → quickdbd_cli-0.3.1}/tests/test_tags.py

@@ -165,6 +165,48 @@ def test_diff_colour_wins_over_tag():
     assert b["color"] == DEFAULT_COLORS["dim"] and "#2e7d32" in svg and DEFAULT_COLORS["dim"] not in svg
 
 
+COLUMNS = """# @color pii #ff9800
+orders
+-
+id PK int
+# The discount.
+# @tag: added
+discount decimal
+legacy varchar  # @tag: removed
+email varchar  # @tag: PII
+"""
+
+
+def test_column_tags():
+    s = compile_text(COLUMNS)
+    cols = s.tables["orders"].columns
+    assert cols["discount"].tags == ["added"] and cols["discount"].comments == ["The discount."]
+    assert cols["legacy"].tags == ["removed"] and cols["legacy"].comments == []
+    assert s.diagnostics == []
+    m = model_json(s)
+    c = {c["name"]: c for c in m["tables"][0]["cols"]}
+    assert c["discount"]["color"] == DEFAULT_COLORS["added"] == "#2e7d32"
+    assert c["legacy"]["color"] == DEFAULT_COLORS["removed"]
+    assert c["email"]["tags"] == ["pii"] and c["email"]["color"] == "#ff9800"
+    assert "tags" not in c["id"] and "color" not in c["id"]
+    assert "tags" not in m["tables"][0]  # column tags don't tag (or colour) the table
+    assert {g["name"]: g["count"] for g in m["tags"]} == {"added": 1, "pii": 1, "removed": 1}
+
+
+def test_column_tags_render_select_and_keys_mode():
+    m = model_json(compile_text(COLUMNS + "\nother\n-\nid int\n"))
+    rt = runtime()
+    rt.load("render.js")
+    assert rt.call("qdbdSelect", m, "tag:removed") == ["orders"]
+    pos = {"orders": [0, 0], "other": [300, 0]}
+    svg = render_svg(m, pos, embed_font=False)
+    assert 'fill="#c62828" fill-opacity=".1"' in svg and 'stroke="#c62828"' in svg  # tinted row, struck name
+    keys = render_svg(m, pos, mode="keys", embed_font=False)
+    assert ">legacy<" in keys and ">email<" in keys  # tagged columns stay visible with keys only
+    xml = render_drawio(m, pos)
+    assert "fontStyle=8;fontColor=#c62828;" in xml and "fontColor=#2e7d32;" in xml
+
+
 def test_dbt_import_writes_dbt_tags(tmp_path):
     def node(uid, name, tags=None, config_tags=None):
         return {

quickdbd_cli-0.3.0/src/quickdbd_cli/__init__.py

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