dbt-tester 0.1.0__tar.gz

dbt_tester-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dbt_tester-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: dbt-tester
+Version: 0.1.0
+Summary: Static analysis and health report generator for dbt projects
+Author-email: Vinoth J <career.vinothj@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: jinja2>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# dbt-tester
+
+`dbt-tester` is a lightweight static analysis tool that inspects dbt projects without running dbt itself. It scans your models, schema YAML files, and compiled manifest metadata to catch missing documentation, test coverage gaps, naming inconsistencies, and lineage issues. The CLI outputs results in the terminal or exports shareable HTML/JSON reports, making it easy to embed into CI pipelines.
+
+## Features
+- Discovers all models, sources, and tests in a dbt project directory
+- Plug-in style check engine grouped by models, tests, docs, lineage, and sources
+- Console, HTML, and JSON reporters with severity levels
+- Configurable failure threshold for CI/CD
+- Simple to extend with custom checks
+
+## Quick start
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+dbt-tester run path/to/dbt_project --format console
+```
+
+- Quotes are required when the project path contains spaces: `dbt-tester run "/home/me/dbt project" --format console`.
+- Use `--format html --output report.html` to produce a shareable artifact (`.html`), or `--format json --output findings.json` for automation payloads.
+- Control CI failure behavior with `--fail-on error|warning`; defaults to `error`.
+
+## Common commands
+
+| Purpose | Command |
+| --- | --- |
+| Install for development | `pip install -e .[dev]` |
+| Run unit tests | `pytest` |
+| Scan current directory | `dbt-tester run . --format console` |
+| Export HTML report | `dbt-tester run . --format html --output dbt_report.html` |
+| Export JSON report | `dbt-tester run . --format json --output dbt_report.json` |
+| Enforce zero warnings in CI | `dbt-tester run . --fail-on warning` |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+pytest
+```
+
+To ship the package:
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

dbt_tester-0.1.0/README.md

@@ -0,0 +1,54 @@
+# dbt-tester
+
+`dbt-tester` is a lightweight static analysis tool that inspects dbt projects without running dbt itself. It scans your models, schema YAML files, and compiled manifest metadata to catch missing documentation, test coverage gaps, naming inconsistencies, and lineage issues. The CLI outputs results in the terminal or exports shareable HTML/JSON reports, making it easy to embed into CI pipelines.
+
+## Features
+- Discovers all models, sources, and tests in a dbt project directory
+- Plug-in style check engine grouped by models, tests, docs, lineage, and sources
+- Console, HTML, and JSON reporters with severity levels
+- Configurable failure threshold for CI/CD
+- Simple to extend with custom checks
+
+## Quick start
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+dbt-tester run path/to/dbt_project --format console
+```
+
+- Quotes are required when the project path contains spaces: `dbt-tester run "/home/me/dbt project" --format console`.
+- Use `--format html --output report.html` to produce a shareable artifact (`.html`), or `--format json --output findings.json` for automation payloads.
+- Control CI failure behavior with `--fail-on error|warning`; defaults to `error`.
+
+## Common commands
+
+| Purpose | Command |
+| --- | --- |
+| Install for development | `pip install -e .[dev]` |
+| Run unit tests | `pytest` |
+| Scan current directory | `dbt-tester run . --format console` |
+| Export HTML report | `dbt-tester run . --format html --output dbt_report.html` |
+| Export JSON report | `dbt-tester run . --format json --output dbt_report.json` |
+| Enforce zero warnings in CI | `dbt-tester run . --fail-on warning` |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+pytest
+```
+
+To ship the package:
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

dbt_tester-0.1.0/dbt_tester/__init__.py

@@ -0,0 +1,4 @@
+"""dbt-tester package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

dbt_tester-0.1.0/dbt_tester/__main__.py

@@ -0,0 +1,7 @@
+"""Enable python -m dbt_tester."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

dbt_tester-0.1.0/dbt_tester/checks/__init__.py

@@ -0,0 +1,24 @@
+"""Check registry."""
+
+from __future__ import annotations
+
+from .doc_checks import ColumnDocumentationCheck, ModelDocumentationCheck
+from .lineage_checks import OrphanModelCheck
+from .model_checks import ModelSchemaPresenceCheck, StagingNamingCheck
+from .source_checks import SourceFreshnessCheck
+from .test_checks import ColumnNotNullCheck, ModelTestsCoverageCheck
+
+
+def get_registered_checks():
+    """Return instantiated checks in execution order."""
+
+    return [
+        ModelSchemaPresenceCheck(),
+        StagingNamingCheck(),
+        ModelDocumentationCheck(),
+        ColumnDocumentationCheck(),
+        ModelTestsCoverageCheck(),
+        ColumnNotNullCheck(),
+        SourceFreshnessCheck(),
+        OrphanModelCheck(),
+    ]

dbt_tester-0.1.0/dbt_tester/checks/base_check.py

@@ -0,0 +1,35 @@
+"""Base class for all dbt-tester checks."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+
+@dataclass
+class Finding:
+    level: str
+    model: str
+    rule: str
+    message: str
+    details: Dict[str, Any] | None = None
+
+
+class BaseCheck(ABC):
+    rule: str
+
+    @abstractmethod
+    def run(self, context: Dict[str, Any]) -> List[Finding]:
+        """Execute the rule and return findings."""
+
+    def _finding(
+        self,
+        *,
+        level: str,
+        model: str,
+        message: str,
+        rule: str | None = None,
+        details: Dict[str, Any] | None = None,
+    ) -> Finding:
+        return Finding(level=level, model=model, rule=rule or self.rule, message=message, details=details)

dbt_tester-0.1.0/dbt_tester/checks/doc_checks.py

@@ -0,0 +1,46 @@
+"""Documentation-related checks."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .base_check import BaseCheck, Finding
+
+
+class ModelDocumentationCheck(BaseCheck):
+    rule = "model_missing_description"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            if not model["defined_in_schema"]:
+                continue
+            if not (model.get("description") or "").strip():
+                findings.append(
+                    self._finding(
+                        level="warning",
+                        model=model["name"],
+                        message="Model description missing in schema.yml",
+                    )
+                )
+        return findings
+
+
+class ColumnDocumentationCheck(BaseCheck):
+    rule = "column_missing_description"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            if not model["columns"]:
+                continue
+            for column in model["columns"]:
+                if not (column.get("description") or "").strip():
+                    findings.append(
+                        self._finding(
+                            level="warning",
+                            model=model["name"],
+                            message=f"Column '{column.get('name')}' missing description",
+                        )
+                    )
+        return findings

dbt_tester-0.1.0/dbt_tester/checks/lineage_checks.py

@@ -0,0 +1,35 @@
+"""Lineage checks that rely on manifest data."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .base_check import BaseCheck, Finding
+
+
+class OrphanModelCheck(BaseCheck):
+    rule = "orphan_model"
+
+    def run(self, context: Dict) -> List[Finding]:
+        manifest = context.get("manifest") or {}
+        nodes = manifest.get("nodes") or {}
+        child_map = manifest.get("child_map") or {}
+        if not nodes:
+            return []
+
+        findings: List[Finding] = []
+        for node_id, node in nodes.items():
+            if node.get("resource_type") != "model":
+                continue
+            model_name = node.get("name", node_id)
+            parents = node.get("depends_on", {}).get("nodes", [])
+            children = child_map.get(node_id, [])
+            if not parents and not children:
+                findings.append(
+                    self._finding(
+                        level="info",
+                        model=model_name,
+                        message="Model has no upstream or downstream refs",
+                    )
+                )
+        return findings

dbt_tester-0.1.0/dbt_tester/checks/model_checks.py

@@ -0,0 +1,52 @@
+"""Model structure checks."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .base_check import BaseCheck, Finding
+
+
+class ModelSchemaPresenceCheck(BaseCheck):
+    rule = "model_missing_schema"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            if not model["defined_in_schema"]:
+                findings.append(
+                    self._finding(
+                        level="warning",
+                        model=model["name"],
+                        message="Model has SQL file but is not declared in schema.yml",
+                    )
+                )
+            if model["missing_sql"]:
+                findings.append(
+                    self._finding(
+                        level="error",
+                        model=model["name"],
+                        message="Model declared in schema.yml but SQL file missing",
+                    )
+                )
+        return findings
+
+
+class StagingNamingCheck(BaseCheck):
+    rule = "staging_naming_mismatch"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            name = model["name"]
+            path = model.get("path") or ""
+            if name.startswith("stg_") and "models/staging" not in path:
+                findings.append(
+                    self._finding(
+                        level="warning",
+                        model=name,
+                        message="Staging model should live under models/staging/",
+                        details={"path": path},
+                    )
+                )
+        return findings

dbt_tester-0.1.0/dbt_tester/checks/source_checks.py

@@ -0,0 +1,24 @@
+"""Source-related checks."""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+from .base_check import BaseCheck, Finding
+
+
+class SourceFreshnessCheck(BaseCheck):
+    rule = "source_missing_freshness"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for name, source in context["sources"].items():
+            if not source.get("freshness"):
+                findings.append(
+                    self._finding(
+                        level="warning",
+                        model=name,
+                        message="Source freshness not defined",
+                    )
+                )
+        return findings

dbt_tester-0.1.0/dbt_tester/checks/test_checks.py

@@ -0,0 +1,57 @@
+"""Test coverage checks."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List
+
+from .base_check import BaseCheck, Finding
+
+
+class ModelTestsCoverageCheck(BaseCheck):
+    rule = "model_missing_tests"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            column_tests = sum(len(col.get("tests", []) or []) for col in model["columns"])
+            total_tests = len(model.get("tests", [])) + column_tests
+            if total_tests == 0:
+                findings.append(
+                    self._finding(
+                        level="error",
+                        model=model["name"],
+                        message="Model has no tests defined",
+                    )
+                )
+        return findings
+
+
+class ColumnNotNullCheck(BaseCheck):
+    rule = "column_missing_not_null"
+
+    def run(self, context: Dict) -> List[Finding]:
+        findings: List[Finding] = []
+        for model in context["models"].values():
+            for column in model["columns"]:
+                name = column.get("name", "")
+                if not name:
+                    continue
+                if name.endswith("_id") or name == "id":
+                    if not _has_test(column.get("tests", []), "not_null"):
+                        findings.append(
+                            self._finding(
+                                level="warning",
+                                model=model["name"],
+                                message=f"Column '{name}' missing not_null test",
+                            )
+                        )
+        return findings
+
+
+def _has_test(tests: Iterable, expected: str) -> bool:
+    for test in tests or []:
+        if isinstance(test, str) and test == expected:
+            return True
+        if isinstance(test, dict) and expected in test:
+            return True
+    return False

dbt_tester-0.1.0/dbt_tester/cli.py

@@ -0,0 +1,48 @@
+"""CLI entrypoint built with Click."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from .config import load_config
+from .core.project_scanner import ProjectScanner
+from .reporters.console_reporter import ConsoleReporter
+from .reporters.html_reporter import HtmlReporter
+from .reporters.json_reporter import JsonReporter
+
+
+@click.group()
+def main() -> None:
+    """dbt-tester: static health checks for dbt projects."""
+
+
+@main.command()
+@click.argument("project_path", type=click.Path(file_okay=False, path_type=Path), default=Path("."))
+@click.option("--format", "format_", type=click.Choice(["console", "html", "json"]), default=None)
+@click.option("--output", default=None, help="Output file path for html/json reporters")
+@click.option("--fail-on", type=click.Choice(["error", "warning"]), default=None)
+def run(project_path: Path, format_: str | None, output: str | None, fail_on: str | None) -> None:
+    """Scan a dbt project and emit a report."""
+
+    config = load_config(project_path)
+    fmt = format_ or config["format"]
+    fail_level = fail_on or config["fail_on"]
+    output_path = output or config["output"]
+
+    scanner = ProjectScanner(project_path)
+    result = scanner.run_all_checks()
+
+    if fmt == "html":
+        HtmlReporter(result).write(output_path if output else f"{output_path}.html")
+    elif fmt == "json":
+        JsonReporter(result).write(output_path if output else f"{output_path}.json")
+    else:
+        ConsoleReporter(result).render()
+
+    counts = result.count_by_level()
+    if fail_level == "error" and counts.get("error", 0) > 0:
+        raise SystemExit(1)
+    if fail_level == "warning" and (counts.get("warning", 0) > 0 or counts.get("error", 0) > 0):
+        raise SystemExit(1)

dbt_tester-0.1.0/dbt_tester/config.py

@@ -0,0 +1,27 @@
+"""Configuration helpers for dbt-tester."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict
+
+from .utils.file_utils import load_yaml
+
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "fail_on": "error",
+    "format": "console",
+    "output": "dbt_tester_report",
+}
+
+
+def load_config(project_path: str | Path) -> Dict[str, Any]:
+    """Load dbt-tester.yml or dbt-tester.yaml from ``project_path``."""
+
+    project = Path(project_path)
+    for name in ("dbt-tester.yml", "dbt-tester.yaml"):
+        candidate = project / name
+        if candidate.exists():
+            data = load_yaml(candidate)
+            return {**DEFAULT_CONFIG, **data}
+    return DEFAULT_CONFIG.copy()

dbt_tester-0.1.0/dbt_tester/core/manifest_reader.py

@@ -0,0 +1,23 @@
+"""Read dbt manifest files when available."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+
+class ManifestReader:
+    """Load manifest.json if present."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def read(self) -> Dict[str, Any]:
+        manifest_path = self.project_root / "target" / "manifest.json"
+        if not manifest_path.exists():
+            return {}
+        try:
+            return json.loads(manifest_path.read_text())
+        except json.JSONDecodeError:
+            return {}

dbt_tester-0.1.0/dbt_tester/core/project_scanner.py

@@ -0,0 +1,121 @@
+"""Entry point for building context and executing checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+from ..checks import get_registered_checks
+from ..checks.base_check import Finding
+from ..utils.file_utils import find_files, read_text, relative_to
+from .manifest_reader import ManifestReader
+from .schema_parser import SchemaParser
+
+
+@dataclass
+class ScanResult:
+    """Holds final findings and allows post-processing."""
+
+    context: Dict[str, Any]
+    findings: List[Finding] = field(default_factory=list)
+
+    def has_errors(self) -> bool:
+        return any(f.level == "error" for f in self.findings)
+
+    def count_by_level(self) -> Dict[str, int]:
+        counts: Dict[str, int] = {"error": 0, "warning": 0, "info": 0}
+        for finding in self.findings:
+            counts[finding.level] = counts.get(finding.level, 0) + 1
+        return counts
+
+
+class ProjectScanner:
+    """Builds the dbt project context and runs all checks."""
+
+    def __init__(self, project_path: str | Path):
+        self.project_path = Path(project_path).resolve()
+        if not self.project_path.exists():
+            raise FileNotFoundError(f"Project path {self.project_path} does not exist")
+
+    def build_context(self) -> Dict[str, Any]:
+        schema_data = SchemaParser(self.project_path).parse()
+        manifest = ManifestReader(self.project_path).read()
+
+        models: Dict[str, Dict[str, Any]] = {}
+        models_dir = self.project_path / "models"
+        if models_dir.exists():
+            for sql_path in find_files(models_dir, {".sql"}):
+                name = sql_path.stem
+                schema_entry = schema_data["models"].get(name)
+                models[name] = self._build_model_record(sql_path, schema_entry)
+
+        # include schema-only definitions
+        for name, schema_entry in schema_data["models"].items():
+            if name not in models:
+                models[name] = self._build_model_record(None, schema_entry, defined_in_schema=True)
+
+        context: Dict[str, Any] = {
+            "project_path": self.project_path,
+            "models": models,
+            "sources": schema_data["sources"],
+            "manifest": manifest,
+            "stats": {
+                "model_count": len(models),
+                "source_count": len(schema_data["sources"]),
+            },
+        }
+        return context
+
+    def run_all_checks(self) -> ScanResult:
+        context = self.build_context()
+        findings: List[Finding] = []
+        for check in get_registered_checks():
+            findings.extend(check.run(context))
+        return ScanResult(context=context, findings=findings)
+
+    def _build_model_record(
+        self,
+        sql_path: Path | None,
+        schema_entry: Dict[str, Any] | None,
+        *,
+        defined_in_schema: bool | None = None,
+    ) -> Dict[str, Any]:
+        if defined_in_schema is None:
+            defined_in_schema = schema_entry is not None
+
+        rel_path = relative_to(sql_path, self.project_path) if sql_path else None
+        sql_text = read_text(sql_path) if sql_path else ""
+        columns = []
+        tests: List[Any] = []
+        description = ""
+        materialized = None
+        meta = {}
+
+        if schema_entry:
+            description = schema_entry.get("description", "") or ""
+            columns = schema_entry.get("columns", []) or []
+            tests = schema_entry.get("tests", []) or []
+            config = schema_entry.get("config", {}) or {}
+            materialized = config.get("materialized")
+            meta = schema_entry.get("meta", {}) or {}
+
+        if sql_path:
+            model_name = sql_path.stem
+        elif schema_entry and schema_entry.get("name"):
+            model_name = schema_entry.get("name")
+        else:
+            model_name = "unknown"
+
+        return {
+            "name": model_name,
+            "path": rel_path,
+            "sql": sql_text,
+            "description": description,
+            "columns": columns,
+            "tests": tests,
+            "materialized": materialized,
+            "meta": meta,
+            "defined_in_schema": defined_in_schema,
+            "missing_sql": sql_path is None,
+        }

dbt_tester-0.1.0/dbt_tester/core/schema_parser.py

@@ -0,0 +1,50 @@
+"""Schema YAML parsing utilities."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List
+
+from ..utils.file_utils import find_files, load_yaml
+
+
+class SchemaParser:
+    """Collect metadata from schema.yml / sources.yml files."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def parse(self) -> Dict[str, Dict[str, Dict]]:
+        models: Dict[str, Dict] = {}
+        sources: Dict[str, Dict] = {}
+
+        schema_paths = list(find_files(self.project_root, {".yml", ".yaml"}))
+        for path in schema_paths:
+            if path.name.startswith("dbt_project"):
+                continue
+            doc = load_yaml(path)
+            for model in doc.get("models", []) or []:
+                name = model.get("name")
+                if not name:
+                    continue
+                models[name] = {
+                    "description": model.get("description", ""),
+                    "columns": model.get("columns", []) or [],
+                    "tests": model.get("tests", []) or [],
+                    "meta": model.get("meta", {}) or {},
+                    "config": model.get("config", {}) or {},
+                }
+            for source in doc.get("sources", []) or []:
+                source_name = source.get("name")
+                for table in source.get("tables", []) or []:
+                    table_name = table.get("name")
+                    if not source_name or not table_name:
+                        continue
+                    key = f"{source_name}.{table_name}"
+                    sources[key] = {
+                        "description": table.get("description", ""),
+                        "freshness": source.get("freshness"),
+                        "meta": table.get("meta", {}) or {},
+                    }
+
+        return {"models": models, "sources": sources}

dbt_tester-0.1.0/dbt_tester/reporters/base_reporter.py

@@ -0,0 +1,23 @@
+"""Reporter base class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from ..core.project_scanner import ScanResult
+
+
+class Reporter(Protocol):
+    def render(self) -> None:  # pragma: no cover - interface only
+        ...
+
+
+class BaseReporter:
+    def __init__(self, result: ScanResult):
+        self.result = result
+
+    def ensure_output_path(self, path: str | Path) -> Path:
+        output_path = Path(path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        return output_path

dbt_tester-0.1.0/dbt_tester/reporters/console_reporter.py

@@ -0,0 +1,41 @@
+"""Console reporter using Rich."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+from ..checks.base_check import Finding
+from .base_reporter import BaseReporter
+
+
+class ConsoleReporter(BaseReporter):
+    def render(self) -> None:
+        console = Console()
+        counts = self.result.count_by_level()
+        summary = Table(title="dbt-tester summary")
+        summary.add_column("Severity")
+        summary.add_column("Count", justify="right")
+        for level in ("error", "warning", "info"):
+            summary.add_row(level, str(counts.get(level, 0)))
+
+        console.print(summary)
+
+        if not self.result.findings:
+            console.print("[green]No findings detected.[/green]")
+            return
+
+        detail = Table(title="Findings", show_lines=False)
+        detail.add_column("Level")
+        detail.add_column("Model")
+        detail.add_column("Rule")
+        detail.add_column("Message")
+        for finding in self.result.findings:
+            detail.add_row(
+                finding.level,
+                finding.model,
+                finding.rule,
+                finding.message,
+            )
+
+        console.print(detail)

dbt_tester-0.1.0/dbt_tester/reporters/html_reporter.py

@@ -0,0 +1,35 @@
+"""HTML reporter built with Jinja2."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from .base_reporter import BaseReporter
+
+
+class HtmlReporter(BaseReporter):
+    template_name = "report.html"
+
+    def __init__(self, result, template_dir: str | Path | None = None):
+        super().__init__(result)
+        self.template_dir = Path(template_dir or Path(__file__).parent / "templates")
+
+    def render(self) -> None:
+        self.write("dbt_tester_report.html")
+
+    def write(self, output_path: str | Path) -> Path:
+        env = Environment(
+            loader=FileSystemLoader(self.template_dir),
+            autoescape=select_autoescape(["html"]),
+        )
+        template = env.get_template(self.template_name)
+        html = template.render(
+            findings=self.result.findings,
+            counts=self.result.count_by_level(),
+            stats=self.result.context.get("stats", {}),
+        )
+        output = self.ensure_output_path(output_path)
+        output.write_text(html)
+        return output

dbt_tester-0.1.0/dbt_tester/reporters/json_reporter.py

@@ -0,0 +1,31 @@
+"""JSON reporter."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .base_reporter import BaseReporter
+
+
+class JsonReporter(BaseReporter):
+    def render(self) -> None:
+        self.write("dbt_tester_report.json")
+
+    def write(self, output_path: str | Path) -> Path:
+        payload = {
+            "counts": self.result.count_by_level(),
+            "findings": [
+                {
+                    "level": f.level,
+                    "model": f.model,
+                    "rule": f.rule,
+                    "message": f.message,
+                    "details": f.details,
+                }
+                for f in self.result.findings
+            ],
+        }
+        output = self.ensure_output_path(output_path)
+        output.write_text(json.dumps(payload, indent=2))
+        return output

dbt_tester-0.1.0/dbt_tester/reporters/templates/report.html

@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>dbt-tester report</title>
+    <style>
+        body { font-family: "Segoe UI", Tahoma, sans-serif; margin: 2rem; background: #f9fafb; color: #0f172a; }
+        h1 { margin-bottom: 0.5rem; }
+        .summary { display: flex; gap: 1rem; margin-bottom: 2rem; }
+        .card { padding: 1rem 1.5rem; border-radius: 0.75rem; background: white; box-shadow: 0 10px 25px rgba(15,23,42,0.08); }
+        table { width: 100%; border-collapse: collapse; margin-top: 1.5rem; background: white; box-shadow: 0 10px 25px rgba(15,23,42,0.08); }
+        th, td { padding: 0.75rem 1rem; border-bottom: 1px solid #e2e8f0; text-align: left; }
+        th { background: #e2e8f0; text-transform: uppercase; letter-spacing: 0.04em; font-size: 0.8rem; }
+        .level-error { color: #b91c1c; font-weight: 600; }
+        .level-warning { color: #b45309; font-weight: 600; }
+        .level-info { color: #0369a1; font-weight: 600; }
+    </style>
+</head>
+<body>
+    <h1>dbt-tester report</h1>
+    <p>{{ stats.model_count }} models scanned · {{ stats.source_count }} sources</p>
+    <section class="summary">
+        <div class="card">
+            <strong>Errors</strong>
+            <div>{{ counts["error"] }}</div>
+        </div>
+        <div class="card">
+            <strong>Warnings</strong>
+            <div>{{ counts["warning"] }}</div>
+        </div>
+        <div class="card">
+            <strong>Info</strong>
+            <div>{{ counts["info"] }}</div>
+        </div>
+    </section>
+
+    <table>
+        <thead>
+            <tr>
+                <th>Level</th>
+                <th>Model</th>
+                <th>Rule</th>
+                <th>Message</th>
+            </tr>
+        </thead>
+        <tbody>
+            {% for finding in findings %}
+            <tr>
+                <td class="level-{{ finding.level }}">{{ finding.level }}</td>
+                <td>{{ finding.model }}</td>
+                <td>{{ finding.rule }}</td>
+                <td>{{ finding.message }}</td>
+            </tr>
+            {% else %}
+            <tr>
+                <td colspan="4">No findings 🎉</td>
+            </tr>
+            {% endfor %}
+        </tbody>
+    </table>
+</body>
+</html>

dbt_tester-0.1.0/dbt_tester/utils/file_utils.py

@@ -0,0 +1,47 @@
+"""Utility helpers for file IO."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Iterable, Iterator, List, Optional
+
+import yaml
+
+
+def find_files(root: Path, suffixes: Iterable[str]) -> Iterator[Path]:
+    """Yield files under ``root`` that match any suffix in ``suffixes``."""
+
+    suffix_set = {s.lower() for s in suffixes}
+    for path in root.rglob("*"):
+        if path.is_file() and path.suffix.lower() in suffix_set:
+            yield path
+
+
+def load_yaml(path: Path) -> Dict:
+    """Safely read a YAML file, returning an empty dict when missing."""
+
+    if not path.exists():
+        return {}
+    data = yaml.safe_load(path.read_text())
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        return {"value": data}
+    return data
+
+
+def read_text(path: Path) -> str:
+    """Return the text contents of ``path`` or empty string when absent."""
+
+    if not path.exists():
+        return ""
+    return path.read_text()
+
+
+def relative_to(path: Path, base: Path) -> str:
+    """Return a POSIX relative path string, falling back to absolute."""
+
+    try:
+        return path.relative_to(base).as_posix()
+    except ValueError:
+        return path.as_posix()

dbt_tester-0.1.0/dbt_tester.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: dbt-tester
+Version: 0.1.0
+Summary: Static analysis and health report generator for dbt projects
+Author-email: Vinoth J <career.vinothj@gmail.com>
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: jinja2>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# dbt-tester
+
+`dbt-tester` is a lightweight static analysis tool that inspects dbt projects without running dbt itself. It scans your models, schema YAML files, and compiled manifest metadata to catch missing documentation, test coverage gaps, naming inconsistencies, and lineage issues. The CLI outputs results in the terminal or exports shareable HTML/JSON reports, making it easy to embed into CI pipelines.
+
+## Features
+- Discovers all models, sources, and tests in a dbt project directory
+- Plug-in style check engine grouped by models, tests, docs, lineage, and sources
+- Console, HTML, and JSON reporters with severity levels
+- Configurable failure threshold for CI/CD
+- Simple to extend with custom checks
+
+## Quick start
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+dbt-tester run path/to/dbt_project --format console
+```
+
+- Quotes are required when the project path contains spaces: `dbt-tester run "/home/me/dbt project" --format console`.
+- Use `--format html --output report.html` to produce a shareable artifact (`.html`), or `--format json --output findings.json` for automation payloads.
+- Control CI failure behavior with `--fail-on error|warning`; defaults to `error`.
+
+## Common commands
+
+| Purpose | Command |
+| --- | --- |
+| Install for development | `pip install -e .[dev]` |
+| Run unit tests | `pytest` |
+| Scan current directory | `dbt-tester run . --format console` |
+| Export HTML report | `dbt-tester run . --format html --output dbt_report.html` |
+| Export JSON report | `dbt-tester run . --format json --output dbt_report.json` |
+| Enforce zero warnings in CI | `dbt-tester run . --fail-on warning` |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+pytest
+```
+
+To ship the package:
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

dbt_tester-0.1.0/dbt_tester.egg-info/SOURCES.txt

@@ -0,0 +1,30 @@
+LICENSE
+README.md
+pyproject.toml
+dbt_tester/__init__.py
+dbt_tester/__main__.py
+dbt_tester/cli.py
+dbt_tester/config.py
+dbt_tester.egg-info/PKG-INFO
+dbt_tester.egg-info/SOURCES.txt
+dbt_tester.egg-info/dependency_links.txt
+dbt_tester.egg-info/entry_points.txt
+dbt_tester.egg-info/requires.txt
+dbt_tester.egg-info/top_level.txt
+dbt_tester/checks/__init__.py
+dbt_tester/checks/base_check.py
+dbt_tester/checks/doc_checks.py
+dbt_tester/checks/lineage_checks.py
+dbt_tester/checks/model_checks.py
+dbt_tester/checks/source_checks.py
+dbt_tester/checks/test_checks.py
+dbt_tester/core/manifest_reader.py
+dbt_tester/core/project_scanner.py
+dbt_tester/core/schema_parser.py
+dbt_tester/reporters/base_reporter.py
+dbt_tester/reporters/console_reporter.py
+dbt_tester/reporters/html_reporter.py
+dbt_tester/reporters/json_reporter.py
+dbt_tester/reporters/templates/report.html
+dbt_tester/utils/file_utils.py
+tests/test_package.py

dbt_tester-0.1.0/dbt_tester.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dbt_tester-0.1.0/dbt_tester.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dbt-tester = dbt_tester.cli:main

dbt_tester-0.1.0/dbt_tester.egg-info/requires.txt

@@ -0,0 +1,8 @@
+click>=8.0
+pyyaml>=6.0
+rich>=13.0
+jinja2>=3.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0

dbt_tester-0.1.0/dbt_tester.egg-info/top_level.txt

@@ -0,0 +1 @@
+dbt_tester

dbt_tester-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dbt-tester"
+version = "0.1.0"
+description = "Static analysis and health report generator for dbt projects"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+  { name = "Vinoth J", email = "career.vinothj@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+  "click>=8.0",
+  "pyyaml>=6.0",
+  "rich>=13.0",
+  "jinja2>=3.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0"
+]
+
+[project.scripts]
+"dbt-tester" = "dbt_tester.cli:main"
+
+[tool.setuptools.package-data]
+"dbt_tester" = ["reporters/templates/*.html"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+addopts = "-q"

dbt_tester-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dbt_tester-0.1.0/tests/test_package.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from dbt_tester.cli import main
+from dbt_tester.core.project_scanner import ProjectScanner
+
+FIXTURE = Path(__file__).parent / "fixtures" / "basic_project"
+
+
+def test_build_context_collects_models_and_sources():
+    scanner = ProjectScanner(FIXTURE)
+    context = scanner.build_context()
+    assert "stg_orders" in context["models"]
+    assert context["stats"]["source_count"] == 1
+
+
+def test_run_all_checks_finds_expected_issues():
+    result = ProjectScanner(FIXTURE).run_all_checks()
+    rules = {finding.rule for finding in result.findings}
+    assert "column_missing_description" in rules
+    assert any(f.level == "error" for f in result.findings)
+
+
+def test_cli_run_generates_output(tmp_path):
+    runner = CliRunner()
+    out_path = tmp_path / "report.json"
+    response = runner.invoke(
+        main,
+        [
+            "run",
+            str(FIXTURE),
+            "--format",
+            "json",
+            "--output",
+            str(out_path),
+            "--fail-on",
+            "warning",
+        ],
+    )
+    assert response.exit_code == 1
+    assert out_path.exists()