dbdocs 1.0.0__tar.gz → 1.0.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdocs
-Version: 1.0.0
+Version: 1.0.1
 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.1}/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.1}/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.1}/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.1}/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>'