sqlbuild 0.2.1__tar.gz → 0.3.0__tar.gz

sqlbuild-0.3.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.0"
+}

{sqlbuild-0.2.1 → sqlbuild-0.3.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.0](https://github.com/chio-labs/sqlbuild/compare/v0.2.1...v0.3.0) (2026-05-05)
+
+
+### Features
+
+* add lineage command ([9aef7d6](https://github.com/chio-labs/sqlbuild/commit/9aef7d69ad556a2ef0ec568f1aed4492a119dfff))
+* add lineage command ([a0af73a](https://github.com/chio-labs/sqlbuild/commit/a0af73adfd5dba1870ff5b3b7293a78967a578c8))
+
 ## [0.2.1](https://github.com/chio-labs/sqlbuild/compare/v0.2.0...v0.2.1) (2026-05-05)
 
 

{sqlbuild-0.2.1 → sqlbuild-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.2.1
+Version: 0.3.0
 Summary: Batch SQL transformation framework
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlbuild-0.2.1 → sqlbuild-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlbuild"
-version = "0.2.1"
+version = "0.3.0"
 description = "Batch SQL transformation framework"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlbuild-0.2.1 → sqlbuild-0.3.0}/src/sqlbuild/cli/commands/main/entry.py

@@ -102,6 +102,23 @@ def _build_parser() -> argparse.ArgumentParser:
     query_parser.add_argument(
         "--no-limit", dest="query_no_limit", action="store_true", default=False
     )
+    lineage_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.LINEAGE)
+    lineage_parser.add_argument("lineage_target", nargs="?", metavar="target")
+    lineage_parser.add_argument("--no-sql-validation", action="store_true", default=False)
+    lineage_parser.add_argument(
+        "--format",
+        dest="lineage_format",
+        choices=("tree", "json", "list"),
+        default="tree",
+    )
+    lineage_parser.add_argument(
+        "--direction",
+        dest="lineage_direction",
+        choices=("upstream", "downstream", "both"),
+        default="upstream",
+    )
+    lineage_parser.add_argument("--depth", dest="lineage_depth", default="all")
+    add_select_args(lineage_parser)
     subparsers.add_parser(CliCommand.CLEAN)
     janitor_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.JANITOR)
     janitor_parser.add_argument("--auto-approve", action="store_true", default=False)
@@ -119,6 +136,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     from sqlbuild.cli.commands.main.compile import run_compile
     from sqlbuild.cli.commands.main.diff import run_diff
     from sqlbuild.cli.commands.main.janitor import run_janitor
+    from sqlbuild.cli.commands.main.lineage import run_lineage
     from sqlbuild.cli.commands.main.plan import run_plan
     from sqlbuild.cli.commands.main.query import run_query
     from sqlbuild.cli.commands.main.run import run_run
@@ -136,6 +154,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         run_clone=run_clone,
         run_diff=run_diff,
         run_query=run_query,
+        run_lineage=run_lineage,
         run_janitor=run_janitor,
     )
     return _main_with_dependencies(argv=argv, handlers=handlers)
@@ -257,6 +276,17 @@ def _main_with_dependencies(
                 tuple(args.select),
                 tuple(args.exclude),
             )
+        if args.command == CliCommand.LINEAGE:
+            return handlers.run_lineage(
+                project_dir,
+                args.no_sql_validation,
+                args.lineage_target,
+                args.lineage_format,
+                args.lineage_direction,
+                args.lineage_depth,
+                tuple(args.select),
+                tuple(args.exclude),
+            )
         if args.command == CliCommand.CLONE:
             if args.from_environment is None or args.to_environment is None:
                 raise CliUserError("clone requires --from and --to")

{sqlbuild-0.2.1 → sqlbuild-0.3.0}/src/sqlbuild/cli/commands/main/helpers/entry/models.py

@@ -41,6 +41,10 @@ class CliNamespace:
     query_format: str = "long"
     query_limit: int | None = 20
     query_no_limit: bool = False
+    lineage_target: str | None = None
+    lineage_format: str = "tree"
+    lineage_direction: str = "upstream"
+    lineage_depth: str = "all"
     full: bool = False
     schema_only: bool = False
     select: list[str] = field(default_factory=list)
@@ -128,4 +132,8 @@ class CliEntrypointHandlers:
         int,
     ]
     run_query: Callable[[Path | None, str | None, str, int | None], int]
+    run_lineage: Callable[
+        [Path | None, bool, str | None, str, str, str, tuple[str, ...], tuple[str, ...]],
+        int,
+    ]
     run_janitor: Callable[[Path | None, bool, bool, int | None], int]

sqlbuild-0.3.0/src/sqlbuild/cli/commands/main/helpers/lineage/__init__.py

@@ -0,0 +1 @@
+"""Lineage command helpers."""

sqlbuild-0.3.0/src/sqlbuild/cli/commands/main/helpers/lineage/models.py

@@ -0,0 +1,55 @@
+"""Lineage command models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sqlbuild.compiler.compile.models import CompiledObjectKey
+
+
+@dataclass(frozen=True)
+class LineageNode:
+    """One displayable lineage graph node."""
+
+    key: CompiledObjectKey
+    relative_path: str | None = None
+    qualified_name: str | None = None
+
+
+@dataclass(frozen=True)
+class LineageGraph:
+    """Selected lineage graph slice."""
+
+    nodes: tuple[LineageNode, ...]
+    edges: tuple[tuple[CompiledObjectKey, CompiledObjectKey], ...]
+    focus_keys: tuple[CompiledObjectKey, ...] = field(default_factory=tuple)
+    direction: str | None = None
+
+
+@dataclass(frozen=True)
+class LineageSelectionAnchors:
+    """Selector anchors used for optional post-selection depth trimming."""
+
+    upstream: frozenset[CompiledObjectKey] = field(default_factory=frozenset)
+    downstream: frozenset[CompiledObjectKey] = field(default_factory=frozenset)
+    retained: frozenset[CompiledObjectKey] = field(default_factory=frozenset)
+
+
+@dataclass(frozen=True)
+class ParsedLineageSelector:
+    """One parsed non-path lineage selector."""
+
+    kind: str
+    value: str
+    upstream: bool = False
+    downstream: bool = False
+
+
+@dataclass(frozen=True)
+class ParsedLineagePathSelector:
+    """One parsed path-between lineage selector."""
+
+    start_name: str
+    end_name: str
+    upstream: bool = False
+    downstream: bool = False

sqlbuild-0.3.0/src/sqlbuild/cli/commands/main/helpers/lineage/output.py

@@ -0,0 +1,187 @@
+"""Lineage output formatting."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+
+from sqlbuild.cli.commands.main.helpers.lineage.models import LineageGraph, LineageNode
+from sqlbuild.compiler.compile.models import CompiledObjectKey
+from sqlbuild.shared.helpers.colors import blue_bold, bold, dim
+
+
+def format_lineage_json(graph: LineageGraph) -> str:
+    """Serialize lineage graph as stable JSON."""
+
+    payload: dict[str, object] = {
+        "nodes": [_serialize_node(node) for node in graph.nodes],
+        "edges": [
+            {"from": _node_id(upstream), "to": _node_id(downstream)}
+            for upstream, downstream in graph.edges
+        ],
+    }
+    if graph.focus_keys:
+        payload["focus"] = [_node_id(key) for key in graph.focus_keys]
+    if graph.direction is not None:
+        payload["direction"] = graph.direction
+    return json.dumps(payload, indent=2)
+
+
+def format_lineage_list(graph: LineageGraph, *, use_color: bool = True) -> str:
+    """Format lineage graph as an edge list."""
+
+    if not graph.edges:
+        return "\n".join(_format_key(node.key, use_color=use_color) for node in graph.nodes)
+    left_width: int = max(len(_node_id(upstream)) for upstream, _downstream in graph.edges)
+    return "\n".join(
+        f"{_format_key(upstream, use_color=use_color)}"
+        f"{' ' * (left_width - len(_node_id(upstream)))} "
+        f"{_style('->', dim, use_color=use_color)} "
+        f"{_format_key(downstream, use_color=use_color)}"
+        for upstream, downstream in graph.edges
+    )
+
+
+def format_lineage_tree(graph: LineageGraph, *, use_color: bool = True) -> str:
+    """Format lineage graph for humans."""
+
+    if len(graph.focus_keys) != 1 or graph.direction is None:
+        return _format_graph_summary(graph, use_color=use_color)
+    focus: CompiledObjectKey = graph.focus_keys[0]
+    node_by_key: dict[CompiledObjectKey, LineageNode] = {node.key: node for node in graph.nodes}
+    title: str = _style("Lineage", blue_bold, use_color=use_color)
+    direction: str = _style(graph.direction, dim, use_color=use_color)
+    lines: list[str] = [
+        f"{title}  {_format_node(node_by_key[focus], use_color=use_color)}  {direction}"
+    ]
+    if graph.direction in {"upstream", "both"}:
+        upstream: dict[CompiledObjectKey, list[CompiledObjectKey]] = {}
+        for parent, child in graph.edges:
+            upstream.setdefault(child, []).append(parent)
+        if graph.direction == "both":
+            lines.append(_style("upstream", blue_bold, use_color=use_color))
+        lines.extend(
+            _format_branch(
+                focus,
+                upstream,
+                node_by_key,
+                prefix="",
+                seen={focus},
+                use_color=use_color,
+            )
+        )
+    if graph.direction in {"downstream", "both"}:
+        downstream: dict[CompiledObjectKey, list[CompiledObjectKey]] = {}
+        for parent, child in graph.edges:
+            downstream.setdefault(parent, []).append(child)
+        if graph.direction == "both":
+            lines.append(_style("downstream", blue_bold, use_color=use_color))
+        lines.extend(
+            _format_branch(
+                focus,
+                downstream,
+                node_by_key,
+                prefix="",
+                seen={focus},
+                use_color=use_color,
+            )
+        )
+    return "\n".join(lines)
+
+
+def _format_graph_summary(graph: LineageGraph, *, use_color: bool) -> str:
+    title: str = _style("Lineage graph", blue_bold, use_color=use_color)
+    counts: str = _style(
+        f"({len(graph.nodes)} nodes, {len(graph.edges)} edges)", dim, use_color=use_color
+    )
+    lines: list[str] = [f"{title}  {counts}"]
+    if graph.edges:
+        lines.extend(
+            f"{_style('  - ', dim, use_color=use_color)}"
+            f"{_format_key(parent, use_color=use_color)} "
+            f"{_style('->', dim, use_color=use_color)} "
+            f"{_format_key(child, use_color=use_color)}"
+            for parent, child in graph.edges
+        )
+    else:
+        lines.extend(f"  {_format_node(node, use_color=use_color)}" for node in graph.nodes)
+    return "\n".join(lines)
+
+
+def _format_branch(
+    key: CompiledObjectKey,
+    deps: dict[CompiledObjectKey, list[CompiledObjectKey]],
+    node_by_key: dict[CompiledObjectKey, LineageNode],
+    *,
+    prefix: str,
+    seen: set[CompiledObjectKey],
+    use_color: bool,
+) -> list[str]:
+    lines: list[str] = []
+    children: list[CompiledObjectKey] = sorted(
+        deps.get(key, ()), key=lambda k: (str(k.resource_type), k.name)
+    )
+    if not children:
+        return lines
+    for index, child in enumerate(children):
+        is_last: bool = index == len(children) - 1
+        branch: str = "└── " if is_last else "├── "
+        child_prefix: str = "    " if is_last else "│   "
+        suffix: str = _style(" (already shown)", dim, use_color=use_color) if child in seen else ""
+        lines.append(
+            f"{_style(prefix + branch, dim, use_color=use_color)}"
+            f"{_format_node(node_by_key[child], use_color=use_color)}{suffix}"
+        )
+        if child in seen:
+            continue
+        lines.extend(
+            _format_branch(
+                child,
+                deps,
+                node_by_key,
+                prefix=prefix + child_prefix,
+                seen=seen | {child},
+                use_color=use_color,
+            )
+        )
+    return lines
+
+
+def _serialize_node(node: LineageNode) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "id": _node_id(node.key),
+        "name": node.key.name,
+        "resource_type": str(node.key.resource_type),
+    }
+    if node.relative_path is not None:
+        payload["relative_path"] = node.relative_path
+    if node.qualified_name is not None:
+        payload["qualified_name"] = node.qualified_name
+    return payload
+
+
+def _format_node(node: LineageNode, *, use_color: bool) -> str:
+    parts: list[str] = [
+        _style(str(node.key.resource_type), dim, use_color=use_color),
+        _style(node.key.name, bold, use_color=use_color),
+    ]
+    if node.relative_path is not None:
+        parts.append(_style(node.relative_path, dim, use_color=use_color))
+    return "  ".join(parts)
+
+
+def _format_key(key: CompiledObjectKey, *, use_color: bool) -> str:
+    return (
+        f"{_style(str(key.resource_type), dim, use_color=use_color)}:"
+        f"{_style(key.name, bold, use_color=use_color)}"
+    )
+
+
+def _node_id(key: CompiledObjectKey) -> str:
+    return f"{key.resource_type}:{key.name}"
+
+
+def _style(text: str, styler: Callable[[str], str], *, use_color: bool) -> str:
+    if not use_color:
+        return text
+    return styler(text)