dbt-tree 0.1.0__py3-none-any.whl

dbt_tree/__init__.py

@@ -0,0 +1,3 @@
+"""dbt-tree: interactive terminal lineage tree for dbt selectors."""
+
+__version__ = "0.1.0"

dbt_tree/cli.py

@@ -0,0 +1,120 @@
+"""Command-line entry point for dbt-tree."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .dbt_runner import DbtError, DbtInvocation, find_dbt, list_all_model_names, list_nodes
+from .graph import (
+    DEFAULT_RESOURCE_TYPES,
+    build_forest,
+    build_graph,
+    extract_focal_names,
+    parse_direction,
+)
+from .render import print_no_match, render_static, suggest
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dbt-tree",
+        description="Interactive terminal lineage tree for dbt selectors.",
+        epilog='example: dbt-tree "my_model+"',
+    )
+    parser.add_argument("--version", action="version", version=f"dbt-tree {__version__}")
+    parser.add_argument(
+        "selector",
+        help='dbt selector, forwarded verbatim to `dbt ls -s` (e.g. "model+", "+model+", "tag:x+").',
+    )
+    parser.add_argument("--target", help="dbt target (passed to dbt ls).")
+    parser.add_argument("--project-dir", help="dbt project directory.")
+    parser.add_argument("--profiles-dir", help="dbt profiles directory.")
+    parser.add_argument(
+        "--dbt-executable", help="Path to dbt (default: $DBT_TREE_DBT or `dbt` on PATH)."
+    )
+    parser.add_argument(
+        "--include-tests",
+        action="store_true",
+        help="Include data tests / unit tests as nodes (off by default).",
+    )
+    parser.add_argument(
+        "--max-depth", type=int, default=0, help="Limit tree depth (0 = unlimited)."
+    )
+    parser.add_argument(
+        "--max-nodes", type=int, default=5000, help="Safety cap on rendered nodes."
+    )
+    parser.add_argument("--no-color", action="store_true", help="Disable color in plain output.")
+    return parser
+
+
+def _resource_types(include_tests: bool) -> frozenset[str]:
+    if include_tests:
+        return DEFAULT_RESOURCE_TYPES | {"test", "unit_test"}
+    return DEFAULT_RESOURCE_TYPES
+
+
+def main(argv: list[str] | None = None) -> int:
+    args, extra = build_parser().parse_known_args(argv)
+
+    try:
+        dbt = find_dbt(args.dbt_executable)
+    except DbtError as exc:
+        print(f"dbt-tree: {exc}", file=sys.stderr)
+        return 2
+
+    inv = DbtInvocation(
+        dbt=dbt,
+        project_dir=args.project_dir,
+        target=args.target,
+        profiles_dir=args.profiles_dir,
+        extra_args=extra or None,
+    )
+
+    try:
+        nodes = list_nodes(args.selector, inv, resource_types=_resource_types(args.include_tests))
+    except DbtError as exc:
+        print(f"dbt-tree: {exc}", file=sys.stderr)
+        return 2
+
+    focal = extract_focal_names(args.selector)
+
+    if not nodes:
+        names = list_all_model_names(inv)
+        suggestions: list[str] = []
+        for want in focal:
+            suggestions += suggest(want, names)
+        print_no_match(args.selector, list(dict.fromkeys(suggestions)), no_color=args.no_color)
+        return 1
+
+    graph = build_graph(nodes)
+    direction = parse_direction(args.selector)
+
+    if direction == "both":
+        focal_ids = [uid for uid, n in graph.nodes.items() if n.name in focal]
+        if focal_ids:
+            up_forest, up_tr = build_forest(
+                graph, direction="up", roots=focal_ids,
+                max_depth=args.max_depth, max_nodes=args.max_nodes,
+            )
+            down_forest, down_tr = build_forest(
+                graph, direction="down", roots=focal_ids,
+                max_depth=args.max_depth, max_nodes=args.max_nodes,
+            )
+            render_static(up_forest, focal, no_color=args.no_color, truncated=up_tr,
+                          header="\u25b2 ancestors")
+            render_static(down_forest, focal, no_color=args.no_color, truncated=down_tr,
+                          header="\u25bc descendants")
+            return 0
+        direction = "down"  # fall back when focal can't be identified
+
+    forest, truncated = build_forest(
+        graph, direction=direction, max_depth=args.max_depth, max_nodes=args.max_nodes
+    )
+    render_static(forest, focal, no_color=args.no_color, truncated=truncated)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dbt_tree/dbt_runner.py

@@ -0,0 +1,203 @@
+"""Run `dbt ls --output json` and parse the result into Node objects.
+
+We deliberately let dbt own selector parsing: whatever the user passes through
+(`model+`, `+model`, `tag:x+`, set unions, ...) is forwarded verbatim, so the
+tool matches dbt's selection exactly with zero re-implementation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+from .graph import DEFAULT_RESOURCE_TYPES, Node
+
+OUTPUT_KEYS = [
+    "unique_id",
+    "name",
+    "resource_type",
+    "depends_on",
+    "config",
+    "original_file_path",
+    "tags",
+    "package_name",
+]
+
+
+class DbtError(RuntimeError):
+    """Raised when the dbt executable is missing or `dbt ls` fails hard."""
+
+
+@dataclass
+class DbtInvocation:
+    dbt: str
+    project_dir: str | None = None
+    target: str | None = None
+    profiles_dir: str | None = None
+    extra_args: list[str] | None = None
+
+
+def _is_fusion(dbt_path: str) -> bool:
+    """dbt Fusion (Rust) is stricter and has a different `ls` surface; detect it."""
+    try:
+        out = subprocess.run(
+            [dbt_path, "--version"], capture_output=True, text=True, timeout=15
+        )
+    except Exception:  # pragma: no cover - best-effort probe
+        return False
+    return "dbt-fusion" in (out.stdout + out.stderr).lower()
+
+
+def find_dbt(explicit: str | None = None) -> str:
+    # Explicit wins. Then $DBT_TREE_DBT. Then the *active virtualenv* (what
+    # `source .../activate` / a `gva`-style alias sets), so dbt-tree follows the
+    # same dbt you'd get by typing `dbt` in that shell. PATH is the last resort.
+    explicit_choice = explicit or os.environ.get("DBT_TREE_DBT")
+    if explicit_choice:
+        resolved = shutil.which(explicit_choice)
+        if resolved:
+            return resolved
+        if os.path.sep in explicit_choice and os.path.exists(explicit_choice):
+            return explicit_choice
+        raise DbtError(
+            f"could not find dbt executable '{explicit_choice}' "
+            "(from --dbt-executable / $DBT_TREE_DBT)."
+        )
+
+    candidates: list[str] = []
+    venv = os.environ.get("VIRTUAL_ENV")
+    if venv:
+        candidates.append(os.path.join(venv, "bin", "dbt"))
+    # Common dbt-core venv locations, so it still works if you forget to activate.
+    home = os.path.expanduser("~")
+    for sub in ("dbt-venv", ".dbt-venv", "venv", ".venv"):
+        candidates.append(os.path.join(home, sub, "bin", "dbt"))
+    path_dbt = shutil.which("dbt")
+    if path_dbt:
+        candidates.append(path_dbt)
+
+    seen: set[str] = set()
+    ordered = [c for c in candidates if c and c not in seen and not seen.add(c)]
+    existing = [c for c in ordered if os.path.exists(c)]
+
+    for cand in existing:
+        if not _is_fusion(cand):
+            return cand
+
+    if existing:
+        # Only Fusion is available; Fusion isn't supported yet, so fail clearly
+        # rather than emit confusing parse errors.
+        raise DbtError(
+            "the only dbt found is dbt Fusion, which is not supported yet "
+            f"({existing[0]}).\nPoint dbt-tree at dbt-core:\n"
+            "  - activate your dbt-core venv first (e.g. `gva`), or\n"
+            "  - set $DBT_TREE_DBT=/path/to/dbt-core/bin/dbt, or\n"
+            "  - pass --dbt-executable /path/to/dbt-core/bin/dbt"
+        )
+
+    raise DbtError(
+        "could not find a dbt executable. Activate your dbt virtualenv (e.g. `gva`), "
+        "or pass --dbt-executable / set $DBT_TREE_DBT."
+    )
+
+
+def _base_cmd(inv: DbtInvocation) -> list[str]:
+    cmd = [inv.dbt, "--quiet", "ls", "--output", "json"]
+    if inv.project_dir:
+        cmd += ["--project-dir", inv.project_dir]
+    if inv.target:
+        cmd += ["--target", inv.target]
+    if inv.profiles_dir:
+        cmd += ["--profiles-dir", inv.profiles_dir]
+    return cmd
+
+
+def parse_nodes(stdout: str, *, resource_types: frozenset[str]) -> list[Node]:
+    nodes: list[Node] = []
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        rtype = obj.get("resource_type")
+        if rtype not in resource_types:
+            continue
+        config = obj.get("config") or {}
+        depends_on = (obj.get("depends_on") or {}).get("nodes") or []
+        uid = obj.get("unique_id") or obj.get("name")
+        if not uid:
+            continue
+        nodes.append(
+            Node(
+                unique_id=uid,
+                name=obj.get("name") or uid,
+                resource_type=rtype,
+                materialized=config.get("materialized"),
+                tags=list(obj.get("tags") or config.get("tags") or []),
+                path=obj.get("original_file_path"),
+                package=obj.get("package_name"),
+                depends_on=list(depends_on),
+            )
+        )
+    return nodes
+
+
+def list_nodes(
+    selector: str,
+    inv: DbtInvocation,
+    *,
+    resource_types: frozenset[str] = DEFAULT_RESOURCE_TYPES,
+) -> list[Node]:
+    cmd = _base_cmd(inv)
+    cmd += ["--output-keys", *OUTPUT_KEYS]
+    cmd += ["--select", selector]
+    if inv.extra_args:
+        cmd += inv.extra_args
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+    except FileNotFoundError as exc:  # pragma: no cover - defensive
+        raise DbtError(str(exc)) from exc
+
+    nodes = parse_nodes(proc.stdout, resource_types=resource_types)
+    # dbt returns 0 for an empty selection; only treat a non-zero exit with no
+    # parseable nodes as a real failure.
+    if not nodes and proc.returncode != 0:
+        raise DbtError(_summarize_failure(inv.dbt, proc.returncode, proc.stderr, proc.stdout))
+    return nodes
+
+
+def _summarize_failure(dbt: str, code: int, stderr: str, stdout: str) -> str:
+    blob = (stderr or stdout or "").strip()
+    error_lines = [ln for ln in blob.splitlines() if "[error]" in ln.lower()]
+    tail = error_lines[-3:] if error_lines else blob.splitlines()[-3:]
+    msg = f"`dbt ls` exited with code {code} and produced no nodes."
+    if tail:
+        msg += "\n  " + "\n  ".join(line.strip() for line in tail)
+    if "dbt-fusion" in blob.lower() or "dbt1060" in blob or "dbt1159" in blob:
+        msg += (
+            "\n\nThis looks like dbt Fusion (stricter parsing). Point dbt-tree at your "
+            "dbt-core install:\n"
+            "  - activate your dbt venv first (e.g. `gva`), or\n"
+            "  - pass --dbt-executable /path/to/dbt-core/bin/dbt, or\n"
+            "  - set $DBT_TREE_DBT."
+        )
+    return msg
+
+
+def list_all_model_names(inv: DbtInvocation) -> list[str]:
+    """Used only to power 'did you mean ...' suggestions on an empty selection."""
+    cmd = _base_cmd(inv)
+    cmd[3:5] = ["--output", "name"]  # swap json -> name
+    cmd += ["--select", "*"]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+    except Exception:  # pragma: no cover - suggestions are best-effort
+        return []
+    return [ln.strip() for ln in proc.stdout.splitlines() if ln.strip() and " " not in ln.strip()]

dbt_tree/graph.py

@@ -0,0 +1,186 @@
+"""Graph model: nodes, adjacency, and the duplicated display forest.
+
+The display forest intentionally *duplicates* shared subtrees (Unix `tree`
+style) so the output mirrors how a node is reached through every path, while a
+visited-path guard keeps cycles (and runaway diamonds) from exploding.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+# Resource types we treat as real lineage nodes by default. Tests / exposures /
+# metrics are excluded unless the caller opts in.
+DEFAULT_RESOURCE_TYPES = frozenset({"model", "seed", "snapshot", "source"})
+
+
+@dataclass
+class Node:
+    unique_id: str
+    name: str
+    resource_type: str
+    materialized: str | None = None
+    tags: list[str] = field(default_factory=list)
+    path: str | None = None
+    package: str | None = None
+    depends_on: list[str] = field(default_factory=list)
+
+    @property
+    def label_suffix(self) -> str:
+        """`(table)` / `(view)` / `(source)` shown after the name."""
+        return self.materialized or self.resource_type
+
+
+@dataclass
+class TreeLine:
+    """One rendered row: a node plus its (duplicated) children."""
+
+    node: Node
+    children: list["TreeLine"] = field(default_factory=list)
+    truncated: bool = False  # hit max_depth / max_nodes; subtree elided
+
+
+@dataclass
+class Graph:
+    nodes: dict[str, Node]
+    children: dict[str, list[str]]  # parent -> children (downstream)
+    parents: dict[str, list[str]]  # child -> parents (upstream)
+    down_roots: list[str]  # no selected parent (sources/focal of `model+`)
+    up_roots: list[str]  # no selected child (focal of `+model`)
+
+
+def build_graph(nodes: list[Node]) -> Graph:
+    """Build both adjacency directions *within the selected set* and find roots.
+
+    Edges are kept only between nodes that are both present in the selection. For
+    ``model+`` the focal node has no selected parent (a ``down_root``); for
+    ``+model`` it has no selected child (an ``up_root``).
+    """
+    by_id = {n.unique_id: n for n in nodes}
+    selection = set(by_id)
+
+    children: dict[str, list[str]] = defaultdict(list)
+    parents: dict[str, list[str]] = defaultdict(list)
+    has_parent: set[str] = set()
+    has_child: set[str] = set()
+
+    for node in nodes:
+        for parent in node.depends_on:
+            if parent in selection:
+                children[parent].append(node.unique_id)
+                parents[node.unique_id].append(parent)
+                has_parent.add(node.unique_id)
+                has_child.add(parent)
+
+    def name_key(uid: str) -> str:
+        return by_id[uid].name.lower()
+
+    for adj in (children, parents):
+        for key in adj:
+            adj[key].sort(key=name_key)
+
+    down_roots = sorted((uid for uid in by_id if uid not in has_parent), key=name_key)
+    up_roots = sorted((uid for uid in by_id if uid not in has_child), key=name_key)
+    return Graph(
+        nodes=by_id,
+        children=dict(children),
+        parents=dict(parents),
+        down_roots=down_roots,
+        up_roots=up_roots,
+    )
+
+
+def build_forest(
+    graph: Graph,
+    *,
+    direction: str = "down",
+    roots: list[str] | None = None,
+    max_depth: int = 0,
+    max_nodes: int = 5000,
+) -> tuple[list[TreeLine], bool]:
+    """Expand the graph into a duplicated display forest.
+
+    ``direction`` is ``"down"`` (walk children) or ``"up"`` (walk parents). When
+    ``roots`` is None, structural roots for that direction are used.
+    ``max_depth=0`` means unlimited depth. Returns ``(forest, truncated)``.
+    """
+    adjacency = graph.children if direction == "down" else graph.parents
+    if roots is None:
+        roots = graph.down_roots if direction == "down" else graph.up_roots
+
+    budget = {"left": max_nodes}
+    hit_budget = {"value": False}
+
+    def expand(uid: str, depth: int, path: frozenset[str]) -> TreeLine:
+        node = graph.nodes[uid]
+        line = TreeLine(node=node)
+
+        if budget["left"] <= 0:
+            hit_budget["value"] = True
+            line.truncated = True
+            return line
+        budget["left"] -= 1
+
+        if max_depth and depth >= max_depth:
+            if adjacency.get(uid):
+                line.truncated = True
+            return line
+
+        # Cycle guard: never re-enter a node already on the current path.
+        next_path = path | {uid}
+        for next_uid in adjacency.get(uid, []):
+            if next_uid in next_path:
+                line.children.append(TreeLine(node=graph.nodes[next_uid], truncated=True))
+                continue
+            line.children.append(expand(next_uid, depth + 1, next_path))
+        return line
+
+    forest = [expand(uid, 0, frozenset()) for uid in roots]
+    return forest, hit_budget["value"]
+
+
+def parse_direction(selector: str) -> str:
+    """Infer orientation from a selector: 'up', 'down', or 'both'.
+
+    Leading ``+`` (incl. ``N+model``) means ancestors; trailing ``+`` (incl.
+    ``model+N``) means descendants; ``@`` implies both. A bare name is 'down'.
+    """
+    up = down = False
+    for token in re.split(r"[\s,]+", selector.strip()):
+        if not token:
+            continue
+        if "@" in token:
+            up = down = True
+        if re.match(r"^\d*\+", token):
+            up = True
+        if re.search(r"\+\d*$", token):
+            down = True
+    if up and down:
+        return "both"
+    if up:
+        return "up"
+    return "down"
+
+
+_OP = re.compile(r"^\d*\+?|\+?\d*$")
+
+
+def extract_focal_names(selector: str) -> set[str]:
+    """Best-effort: pull bare model names out of a selector for `*` marking.
+
+    Strips graph operators (`+`, leading/trailing depth digits) and ignores
+    method selectors (`tag:`, `path:`, ...) and set operators.
+    """
+    focal: set[str] = set()
+    for token in re.split(r"[\s,]+", selector.strip()):
+        if not token or ":" in token or "@" in token:
+            continue
+        bare = token.strip("+")
+        bare = re.sub(r"^\d+", "", bare)
+        bare = re.sub(r"\d+$", "", bare)
+        bare = bare.strip("+")
+        if bare:
+            focal.add(bare.split(".")[-1])
+    return focal

dbt_tree/render.py

@@ -0,0 +1,68 @@
+"""Static (non-interactive) rendering with rich, plus not-found suggestions."""
+
+from __future__ import annotations
+
+import difflib
+
+from rich.console import Console
+from rich.tree import Tree as RichTree
+
+from .graph import Node, TreeLine
+
+RESOURCE_STYLE = {
+    "model": "cyan",
+    "source": "green",
+    "seed": "yellow",
+    "snapshot": "magenta",
+}
+
+
+def node_label(node: Node, focal: set[str]) -> str:
+    style = RESOURCE_STYLE.get(node.resource_type, "white")
+    star = " [bold yellow]*[/bold yellow]" if node.name in focal else ""
+    return f"[{style}]{node.name}[/{style}] [dim]({node.label_suffix})[/dim]{star}"
+
+
+def _attach(parent: RichTree, line: TreeLine, focal: set[str]) -> None:
+    for child in line.children:
+        branch = parent.add(node_label(child.node, focal))
+        if child.truncated:
+            branch.add("[dim]…[/dim]")
+        _attach(branch, child, focal)
+
+
+def render_static(
+    forest: list[TreeLine],
+    focal: set[str],
+    *,
+    no_color: bool = False,
+    truncated: bool = False,
+    header: str | None = None,
+) -> None:
+    console = Console(no_color=no_color, highlight=False)
+    if header:
+        console.print(f"[bold]{header}[/bold]")
+    if not forest:
+        console.print("[yellow]0 nodes matched the selector.[/yellow]")
+        return
+    for root in forest:
+        tree = RichTree(node_label(root.node, focal))
+        if root.truncated:
+            tree.add("[dim]…[/dim]")
+        _attach(tree, root, focal)
+        console.print(tree)
+    if truncated:
+        console.print("[dim]…output truncated (node limit reached; raise --max-nodes).[/dim]")
+
+
+def suggest(name: str, candidates: list[str], n: int = 5) -> list[str]:
+    return difflib.get_close_matches(name, candidates, n=n, cutoff=0.5)
+
+
+def print_no_match(selector: str, suggestions: list[str], *, no_color: bool = False) -> None:
+    console = Console(no_color=no_color, stderr=True, highlight=False)
+    console.print(f"[yellow]0 nodes matched[/yellow] selector: [bold]{selector}[/bold]")
+    if suggestions:
+        console.print("did you mean:")
+        for s in suggestions:
+            console.print(f"  [cyan]{s}[/cyan]")

dbt_tree-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: dbt-tree
+Version: 0.1.0
+Summary: Pretty terminal lineage tree for dbt selectors (dbt-tree "model+").
+Project-URL: Homepage, https://github.com/KarthikRajashekaran/dbt-tree
+Project-URL: Issues, https://github.com/KarthikRajashekaran/dbt-tree/issues
+Author: Karthik Rajashekaran
+License: Apache-2.0
+License-File: LICENSE
+Keywords: cli,dag,data-engineering,dbt,lineage,tree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dbt-tree
+
+Pretty terminal lineage tree for dbt selectors. Run a selector, get a readable
+tree of the resulting DAG right in your terminal — no docs server, no browser.
+
+```bash
+dbt-tree "my_model+"
+```
+
+`dbt-tree` forwards the selector **verbatim** to `dbt ls`, so every dbt selector
+works exactly as it does in dbt itself: `model+`, `+model`, `+model+`,
+`2+model+3`, `tag:nightly+`, `path:models/marts`, set unions, and so on.
+
+## Requirements
+
+- A working **dbt-core** install that you can run as `dbt` (any virtualenv tool is
+  fine — `venv`, `virtualenv`, `conda`, `poetry`, `uv`, …). The only requirement
+  is that the `dbt` executable is reachable (active venv, on `PATH`, or via
+  `$DBT_TREE_DBT` / `--dbt-executable`).
+- Python 3.10+.
+
+`dbt ls` is parse-only, so **no warehouse connection is needed** to draw the tree.
+
+## Install
+
+Install into the **same environment as your dbt** so they share a `PATH`:
+
+```bash
+pip install dbt-tree           # once published
+# or, from source:
+pip install "git+https://github.com/KarthikRajashekaran/dbt-tree.git"
+```
+
+`dbt` itself is **not** a Python dependency — `dbt-tree` shells out to your
+existing dbt rather than pinning a version.
+
+### Which dbt does it use?
+
+Resolution order:
+
+1. `--dbt-executable`
+2. `$DBT_TREE_DBT`
+3. **the active virtualenv** (`$VIRTUAL_ENV/bin/dbt`) — so once you activate your
+   dbt venv, dbt-tree uses the same dbt as your shell
+4. `dbt` on `PATH`
+
+dbt-tree prefers **dbt-core** and will skip a **dbt Fusion** binary when a core
+install is available (Fusion's stricter parsing and different `ls` surface aren't
+supported yet). 
+
+### Recommended workflow:
+
+```bash
+gva # activate your dbt venv (dbt-core)
+dbt-tree "my_model+"
+```
+
+Tip: `pip install` dbt-tree *into that same dbt venv* so `gva` puts both `dbt` and
+`dbt-tree` on your `PATH` together.
+
+## Usage
+
+```bash
+# Downstream lineage
+dbt-tree "my_model+"
+
+# Upstream lineage
+dbt-tree "+my_model"
+
+# Scope / dbt passthrough
+dbt-tree "tag:nightly+" --target prod --project-dir dbt/my_project
+```
+
+Example output:
+
+```text
+my_model (view) *
+└── stg_orders (table)
+    └── int_orders_joined (table)
+        ├── fct_orders (table)
+        │   ├── mart_revenue (table)
+        │   └── ...
+        └── fct_order_items (table)
+```
+
+The originally-selected model is marked with `*`. Nodes are colored by resource
+type; the suffix shows materialization (`table`/`view`) or resource type
+(`source`/`seed`/`snapshot`).
+
+### Orientation follows the selector
+
+The tree is rooted so the focal model is always at the top:
+
+- `model+` (downstream) — root is the model, children are its descendants.
+- `+model` (upstream) — root is the model, children are its **ancestors** (up to
+  sources/seeds).
+- `+model+` (both) — two sections: `▲ ancestors` then `▼ descendants`.
+
+## How it works
+
+1. Runs `dbt --quiet ls --output json --output-keys ... --select <selector>`.
+2. Keeps models, sources, seeds, and snapshots (tests off unless `--include-tests`).
+3. Builds child adjacency **within the selected set**, finds roots, and expands a
+   duplicated tree (Unix `tree` style) with cycle and node-count guards.
+4. Renders a `rich` tree (duplicating shared subtrees, `tree`-command style).
+
+## Options
+
+| flag | default | meaning |
+|---|---|---|
+| `--target` | — | dbt target |
+| `--project-dir` | — | dbt project directory |
+| `--profiles-dir` | — | dbt profiles directory |
+| `--dbt-executable` | `dbt` | path to dbt |
+| `--include-tests` | off | include data/unit tests as nodes |
+| `--max-depth` | `0` | limit depth (0 = unlimited) |
+| `--max-nodes` | `5000` | safety cap on rendered nodes |
+| `--no-color` | off | disable color in plain output |
+
+Unknown flags are forwarded to `dbt ls` as an escape hatch.
+
+## Limitations
+
+- **Single project.** Lineage covers whatever `dbt ls` resolves in the active
+  project; it does not stitch across sibling projects in a monorepo.
+- Selector parsing is dbt's, so behavior matches your installed dbt version.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+Apache-2.0

dbt_tree-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dbt_tree/__init__.py,sha256=dqEOSVwhczP9c0XasZBKP5ABGQBjD8_Q6eo7V25veYQ,92
+dbt_tree/cli.py,sha256=LkSn7foo3kEct0xOeykSBSGOm-zY94Cfd7knQCE01Qs,4154
+dbt_tree/dbt_runner.py,sha256=IsZEmiPCvyY27IOHxrvCKWoaogISSLH2nAQNGniC-_8,7135
+dbt_tree/graph.py,sha256=7bwxW85Gv5UmblWHOpBqytbDOchr3_urUMoyjl6So0E,6109
+dbt_tree/render.py,sha256=lGdtNA0iVzkWo6f4XTuoVFJREXXaXiYl-DmMtG-ci10,2163
+dbt_tree-0.1.0.dist-info/METADATA,sha256=izZ9AsPNpOEaVh_JG7POdHmIu2bNrHc1nwMa-imdt1U,5116
+dbt_tree-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+dbt_tree-0.1.0.dist-info/entry_points.txt,sha256=K_kbPLvjap7JhUF0ZRKhcBNuRfYjexY52I1-JyQBSQU,47
+dbt_tree-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+dbt_tree-0.1.0.dist-info/RECORD,,

dbt_tree-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

dbt_tree-0.1.0.dist-info/entry_points.txt

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

dbt_tree-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.