dbdocs 1.0.0__tar.gz → 1.0.2__tar.gz

{dbdocs-1.0.0 → dbdocs-1.0.2}/.gitignore

@@ -166,3 +166,4 @@ pnpm-debug.log*
 
 # dbdocs DEBUG file log
 logs/
+.DS_Store

{dbdocs-1.0.0 → dbdocs-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdocs
-Version: 1.0.0
+Version: 1.0.2
 Summary: Alternative dbt docs site: Catalog + ERD + column-level lineage
 Project-URL: Homepage, https://github.com/datnguye/dbt-docs
 Project-URL: Repository, https://github.com/datnguye/dbt-docs

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/core/config.py

@@ -8,6 +8,23 @@ from dbdocs.core.exceptions import DbDocsConfigError
 DEFAULT_CONFIG_FILENAME = "dbdocs.yml"
 
 
+def _resolve_within_cwd(value: str, field_name: str) -> Path:
+    """Resolve *value* against cwd; reject a relative path that escapes the cwd.
+
+    An absolute *value* is resolved as-is (the caller's deliberate choice — this
+    is documented behaviour and must not be rejected).  A relative *value* is
+    resolved against ``Path.cwd()`` and then checked: if the result is not
+    inside (or equal to) the cwd, ``DbDocsConfigError`` is raised.
+    """
+    base = Path.cwd().resolve()
+    candidate = Path(value)
+    resolved = candidate if candidate.is_absolute() else (base / candidate)
+    resolved = resolved.resolve()
+    if not candidate.is_absolute() and resolved != base and base not in resolved.parents:
+        raise DbDocsConfigError(f"{field_name} {value!r} escapes the project directory ({base}).")
+    return resolved
+
+
 @dataclass
 class DbDocsConfig:
     """Site configuration for a dbdocs build.
@@ -103,8 +120,9 @@ class DbDocsConfig:
         directory **at access time** — this is intentional and must stay aligned
         with dbterd's ``DbtErd``, which also reads artifacts from ``./target``
         relative to the cwd. An absolute ``target_dir`` is returned unchanged.
+        A relative path that would escape the cwd raises ``DbDocsConfigError``.
         """
-        return str(Path.cwd() / self.target_dir)
+        return str(_resolve_within_cwd(self.target_dir, "target_dir"))
 
     @property
     def output_path(self) -> str:
@@ -113,5 +131,6 @@ class DbDocsConfig:
         Resolved against the cwd at access time, mirroring ``target_path`` — a
         relative ``output_dir`` follows the working directory, an absolute one is
         returned unchanged.
+        A relative path that would escape the cwd raises ``DbDocsConfigError``.
         """
-        return str(Path.cwd() / self.output_dir)
+        return str(_resolve_within_cwd(self.output_dir, "output_dir"))

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/extract/nodes.py

@@ -12,27 +12,52 @@ from typing import Any
 from dbdocs.core.artifacts import NODE_PREFIXES, db_schema, node_name
 
 
+def _column_entry(name: str, manifest_column: Any, col_type: str) -> dict:
+    """One column record. Newlines in the description become ``<br>`` for HTML."""
+    description = getattr(manifest_column, "description", "") or "" if manifest_column else ""
+    return {
+        "name": name,
+        "type": col_type or "",
+        "tags": (getattr(manifest_column, "tags", []) or []) if manifest_column else [],
+        "description": description.replace("\n", "<br>"),
+    }
+
+
 def _columns(model: Any, catalog_node: Any) -> list:
-    """Merge manifest column metadata (description/tags) with catalog types.
+    """Build a node's columns: the manifest is the source of truth, the catalog
+    enriches it.
+
+    The **manifest** decides which columns are documented and carries their
+    metadata (description, tags, ``data_type``); the **catalog** *enriches* — it
+    supplies the warehouse-confirmed type and any columns the manifest didn't
+    document. It never replaces the manifest, so a model absent from a
+    stale/partial ``catalog.json`` still shows every documented column.
 
-    Iterates the catalog's columns (the warehouse truth for which columns exist
-    and their types) and layers on the manifest description/tags when present.
-    Newlines in descriptions become ``<br>`` so they survive HTML rendering.
+    Manifest columns come first, in manifest order, each with its type enriched
+    from the catalog when present (falling back to the manifest ``data_type``).
+    The catalog keys columns by the warehouse's casing (Snowflake upper-cases
+    them) while the manifest keeps the modeled casing, so the catalog type lookup
+    is case-insensitive. Catalog-only columns are appended afterwards.
     """
     manifest_columns = getattr(model, "columns", {}) or {}
     catalog_columns = getattr(catalog_node, "columns", {}) or {} if catalog_node else {}
+    catalog_by_lower = {str(name).lower(): col for name, col in catalog_columns.items()}
+
     columns = []
-    for name in catalog_columns:
-        manifest_column = manifest_columns.get(name)
-        description = getattr(manifest_column, "description", "") or "" if manifest_column else ""
-        columns.append(
-            {
-                "name": name,
-                "type": catalog_columns[name].type,
-                "tags": (getattr(manifest_column, "tags", []) or []) if manifest_column else [],
-                "description": description.replace("\n", "<br>"),
-            }
+    seen_lower = set()
+    for name, manifest_column in manifest_columns.items():
+        lower = str(name).lower()
+        seen_lower.add(lower)
+        catalog_column = catalog_by_lower.get(lower)
+        col_type = getattr(catalog_column, "type", None) or getattr(
+            manifest_column, "data_type", None
         )
+        columns.append(_column_entry(name, manifest_column, col_type or ""))
+
+    for name, catalog_column in catalog_columns.items():
+        if str(name).lower() in seen_lower:
+            continue
+        columns.append(_column_entry(name, None, getattr(catalog_column, "type", "") or ""))
     return columns
 
 

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/builder.py

@@ -9,11 +9,12 @@ data → write ``index.html`` + a debug ``dbdocs-data.json``.
 import json
 from datetime import datetime
 from pathlib import Path
-from shutil import copytree
+from shutil import copytree, rmtree
 from typing import Any
 
 from dbdocs.core.artifacts import adapter_type, load_artifacts
-from dbdocs.core.config import DbDocsConfig
+from dbdocs.core.config import DbDocsConfig, _resolve_within_cwd
+from dbdocs.core.exceptions import DbDocsConfigError
 from dbdocs.core.log import logger
 from dbdocs.extract.column_lineage import ColumnLineageExtractor
 from dbdocs.extract.erd import build_erd, build_erd_data
@@ -66,12 +67,16 @@ class ReportBuilder:
     def _read_readme(self) -> str:
         """The project README markdown (rendered on the overview), or ``""``.
 
-        ``config.readme`` is a path relative to the cwd; a missing file or an
-        empty config value just yields no README section.
+        ``config.readme`` is a path relative to the cwd; a missing file, an
+        empty config value, or a relative path that escapes the cwd all yield
+        no README section (fail-soft — a bad README must never sink generate).
         """
         if not self.config.readme:
             return ""
-        path = Path(self.config.readme)
+        try:
+            path = _resolve_within_cwd(self.config.readme, "readme")
+        except DbDocsConfigError:
+            return ""
         try:
             return path.read_text(encoding="utf-8")
         except OSError:
@@ -109,7 +114,9 @@ class ReportBuilder:
     def generate(self, output_dir: "str | None" = None) -> str:
         """Render the site into ``output_dir`` (or config's). Returns its path."""
         out = Path(output_dir) if output_dir else Path(self.config.output_path)
-        out.mkdir(parents=True, exist_ok=True)
+        if out.exists():
+            rmtree(out)
+        out.mkdir(parents=True)
         copytree(src=BUNDLE_DIR, dst=out, dirs_exist_ok=True)
 
         data = self.build_data()
@@ -117,7 +124,7 @@ class ReportBuilder:
         index.write_text(inject(index.read_text(encoding="utf-8"), data), encoding="utf-8")
         # Compact, not indented — keeps the debug dump cheap on large projects.
         (out / "dbdocs-data.json").write_text(
-            json.dumps(data, separators=(",", ":"), default=self._json_default),
+            json.dumps(data, separators=(",", ":"), sort_keys=True, default=self._json_default),
             encoding="utf-8",
         )
 

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/bundle/assets/app.js

@@ -120,12 +120,23 @@
       el("span", {}, ["Generated by "]),
       el("a", { href: "https://github.com/datnguye/dbt-docs", target: "_blank", rel: "noopener" }, ["dbdocs"]),
     ]);
+    var meta = footerMeta();
+    if (meta) left.appendChild(el("span", { class: "cf-meta" }, [" · " + meta]));
     var right = el("a", { class: "cf-top", href: "#", onclick: function (e) { e.preventDefault(); app.scrollTop = 0; } }, ["↑ Back to top"]);
     foot.appendChild(left);
     foot.appendChild(right);
     return foot;
   }
 
+  /* "snowflake · N column-lineage edges" — the build metadata shown in the
+     content footer. The "Generated X" part lives in the topbar (see boot). */
+  function footerMeta() {
+    var parts = [];
+    if (META.adapter_type) parts.push(META.adapter_type);
+    parts.push(Object.keys(COLLIN).length + " column-lineage edges");
+    return parts.join(" · ");
+  }
+
   var RTYPE_ORDER = { model: 0, snapshot: 1, seed: 2, source: 3 };
 
   function buildNav() {
@@ -456,17 +467,6 @@
     link.hidden = false;
   }
 
-  function initTopbarMeta() {
-    var box = document.getElementById("topbar-meta");
-    if (!box) return;
-    var parts = [];
-    if (META.generated_at) parts.push("Generated " + META.generated_at);
-    if (META.adapter_type) parts.push(META.adapter_type);
-    parts.push(Object.keys(COLLIN).length + " column-lineage edges");
-    box.textContent = parts.join(" · ");
-    box.hidden = false;
-  }
-
   function initFooter() {
     var footer = document.getElementById("site-footer");
     if (!footer) return;
@@ -486,8 +486,12 @@
   function boot() {
     document.getElementById("brand-name").textContent = META.site_name || "dbt docs";
     document.title = META.site_name || "dbt docs";
+    if (META.generated_at) {
+      var gen = document.getElementById("brand-generated");
+      gen.textContent = "Generated " + META.generated_at;
+      gen.hidden = false;
+    }
     initRepo();
-    initTopbarMeta();
     initFooter();
     initTheme();
     buildNav();

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/bundle/assets/style.css

@@ -52,8 +52,9 @@ code, pre { font-family: "SF Mono", "Roboto Mono", Menlo, Consolas, monospace; }
   background: var(--bg-elev); border-bottom: 1px solid var(--border);
   position: sticky; top: 0; z-index: 30;
 }
-.brand { display: flex; align-items: center; gap: 8px; font-weight: 600; min-width: 160px; }
-.brand-mark { display: block; width: 24px; height: 24px; border-radius: 6px; }
+.brand { display: flex; align-items: baseline; gap: 8px; font-weight: 600; min-width: 160px; }
+.brand-mark { display: block; width: 24px; height: 24px; border-radius: 6px; align-self: center; }
+.brand-generated { color: var(--text-soft); font-size: 12px; font-weight: 400; white-space: nowrap; }
 .search-wrap { position: relative; flex: 1; max-width: 520px; }
 #search {
   width: 100%; padding: 7px 12px; border-radius: var(--radius);
@@ -118,21 +119,16 @@ code, pre { font-family: "SF Mono", "Roboto Mono", Menlo, Consolas, monospace; }
 }
 .footer-copy { color: var(--text-soft); font-size: 12px; }
 
-/* Build metadata in the header (generated / adapter / edges) */
-.topbar-meta {
-  color: var(--text-soft); font-size: 11.5px; white-space: nowrap;
-  padding-right: 6px; flex-shrink: 0;
-}
-@media (max-width: 1100px) { .topbar-meta { display: none; } }
-
 /* End-of-page content footer */
 .content-foot {
   display: flex; align-items: center; justify-content: space-between; gap: 12px;
   margin-top: 40px; padding-top: 16px; border-top: 1px solid var(--border);
   color: var(--text-soft); font-size: 12px;
 }
-.content-foot .cf-left { display: inline-flex; align-items: center; gap: 6px; }
+.content-foot .cf-left { display: inline-flex; align-items: center; gap: 6px; flex-wrap: wrap; }
 .content-foot .cf-left .ic { color: var(--text-soft); }
+/* Build metadata (generated / adapter / edges) appended to the footer's left */
+.content-foot .cf-meta { color: var(--text-soft); }
 .content-foot .cf-top { color: var(--text-soft); }
 .content-foot .cf-top:hover { color: var(--accent); }
 .bmc {

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/bundle/index.html

@@ -14,8 +14,8 @@
     <div class="brand">
       <img class="brand-mark" src="assets/favicon.svg" alt="" width="24" height="24" />
       <span class="brand-name" id="brand-name">dbt docs</span>
+      <span class="brand-generated" id="brand-generated" hidden></span>
     </div>
-    <div class="topbar-meta" id="topbar-meta" hidden></div>
     <div class="search-wrap">
       <input id="search" type="search" placeholder="Search models, sources, columns…" autocomplete="off" />
       <div id="search-results" class="search-results" hidden></div>

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/deploy.py

@@ -14,6 +14,7 @@ the output dir onto a ``gh-pages`` branch and pushes it.
 """
 
 import json
+import re
 import subprocess
 from pathlib import Path
 from shutil import copytree, rmtree
@@ -25,6 +26,17 @@ from dbdocs.site.builder import ReportBuilder
 
 VERSIONS_FILE = "versions.json"
 
+#: Allows only alphanumerics, dots, underscores, and hyphens — a safe single path segment.
+_SAFE_SEGMENT = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def _validate_segment(value: str, kind: str) -> None:
+    """Raise :class:`DeployError` if *value* is not a safe single path segment."""
+    if not _SAFE_SEGMENT.match(value) or value in {".", ".."}:
+        raise DeployError(
+            f"Invalid {kind} {value!r}: must match ^[A-Za-z0-9._-]+$ and not be '.' or '..'."
+        )
+
 
 def _read_versions(output_root: Path) -> list:
     path = output_root / VERSIONS_FILE
@@ -57,6 +69,9 @@ def deploy(
     title: "str | None" = None,
 ) -> str:
     """Generate ``version`` into the output root and update the version index."""
+    _validate_segment(version, "version")
+    if alias is not None:
+        _validate_segment(alias, "alias")
     output_root = Path(config.output_path)
     version_dir = output_root / version
     if version_dir.exists():
@@ -85,6 +100,7 @@ def delete(config: DbDocsConfig, version: str, push: bool = False) -> None:
 
     Raises :class:`DeployError` if the version isn't deployed.
     """
+    _validate_segment(version, "version")
     output_root = Path(config.output_path)
     versions = _read_versions(output_root)
     entry = next((v for v in versions if v.get("version") == version), None)
@@ -95,6 +111,7 @@ def delete(config: DbDocsConfig, version: str, push: bool = False) -> None:
     if version_dir.exists():
         rmtree(version_dir)
     for alias in entry.get("aliases", []):
+        _validate_segment(alias, "alias")
         alias_dir = output_root / alias
         if alias_dir.exists():
             rmtree(alias_dir)

{dbdocs-1.0.0 → dbdocs-1.0.2}/dbdocs/site/inject.py

@@ -16,9 +16,9 @@ INJECT_MARKER = "<!-- DBDOCS_DATA -->"
 
 def data_script(data: dict) -> str:
     """The ``<script>`` tag that sets ``window.dbdocsData`` from ``data``."""
-    payload = base64.b64encode(json.dumps(data, separators=(",", ":")).encode("utf-8")).decode(
-        "ascii"
-    )
+    payload = base64.b64encode(
+        json.dumps(data, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    ).decode("ascii")
     return f'<script>window.dbdocsData = JSON.parse(atob("{payload}"));</script>'