dbt-data-contracts 0.1.0__py3-none-any.whl

dbt_contracts/__init__.py

@@ -0,0 +1,3 @@
+"""dbt_contracts: A lightweight data contract control plane for multi-repository dbt ecosystems."""
+
+__version__ = "0.1.0"

dbt_contracts/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI entry point and command modules."""
+
+from dbt_contracts.cli.app import app
+
+__all__ = ["app"]

dbt_contracts/cli/app.py

@@ -0,0 +1,56 @@
+"""Main Typer CLI entry point for dbt_contracts."""
+
+import typer
+
+from dbt_contracts import __version__
+from dbt_contracts.cli.check import check_command
+from dbt_contracts.cli.consumer import app as consumer_app
+from dbt_contracts.cli.ingest import ingest_command
+from dbt_contracts.cli.publish import publish_command
+from dbt_contracts.cli.registry import app as registry_app
+
+app = typer.Typer(
+    name="dbt-contracts",
+    help="Data contract control plane for multi-repository dbt ecosystems.",
+    no_args_is_help=True,
+)
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"dbt-contracts version {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None,
+        "--version",
+        "-V",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """dbt-contracts: Data contract control plane for dbt."""
+
+
+# Register top-level commands
+app.command(name="ingest", help="Ingest and inspect public models from a dbt manifest.")(
+    ingest_command
+)
+app.command(name="publish", help="Publish public dbt models as versioned contracts.")(
+    publish_command
+)
+app.command(name="check", help="Check proposed contract changes against registry and consumers.")(
+    check_command
+)
+
+# Register sub-apps
+app.add_typer(consumer_app, name="consumer", help="Manage consumer contract declarations.")
+app.add_typer(registry_app, name="registry", help="Query the contract registry.")
+
+
+if __name__ == "__main__":
+    app()

dbt_contracts/cli/check.py

@@ -0,0 +1,112 @@
+"""CLI command for CI/PR contract compatibility gating."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dbt_contracts.compatibility.engine import CompatibilityEngine
+from dbt_contracts.dbt.ingestion import DbtManifestIngestor
+from dbt_contracts.domain.compatibility import CompatibilityResult
+from dbt_contracts.exceptions import DbtContractsError
+from dbt_contracts.registry.sqlite import SqliteContractRegistry
+from dbt_contracts.reporting.console import ConsoleReporter
+from dbt_contracts.reporting.json import render_json
+
+app = typer.Typer(
+    help="Check proposed contract changes against published contracts and registered consumers."
+)
+
+
+@app.callback(invoke_without_command=True)
+def check_command(
+    manifest: Annotated[
+        Path,
+        typer.Option(
+            "--manifest",
+            "-m",
+            help="Path to dbt manifest.json file representing proposed changes.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = Path("target/manifest.json"),
+    registry_path: Annotated[
+        Path,
+        typer.Option(
+            "--registry",
+            "-r",
+            help="Path to SQLite contract registry database file.",
+        ),
+    ] = Path(".contracts.db"),
+    proposed_version: Annotated[
+        str | None,
+        typer.Option(
+            "--proposed-version",
+            "-v",
+            help="Proposed contract version to evaluate (e.g. 1.1.0 or 2.0.0).",
+        ),
+    ] = None,
+    product: Annotated[
+        str | None,
+        typer.Option("--product", "-p", help="Override data product name."),
+    ] = None,
+    all_models: Annotated[
+        bool,
+        typer.Option("--all", "-a", help="Check all models, not just public models."),
+    ] = False,
+    format_output: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """Evaluate proposed contracts against registry for breaking changes and consumer impact."""
+    ingestor = DbtManifestIngestor(
+        default_version=proposed_version or "1.0.0",
+        include_all_models=all_models,
+    )
+
+    try:
+        proposed_contracts = ingestor.parse_manifest_file(
+            manifest_path=manifest,
+            version_override=proposed_version,
+            product_override=product,
+        )
+    except DbtContractsError as e:
+        typer.secho(f"Error parsing manifest: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from e
+
+    if not proposed_contracts:
+        typer.secho("No public contracts found to evaluate.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=0)
+
+    registry = SqliteContractRegistry(db_path=registry_path)
+    engine = CompatibilityEngine()
+
+    results: list[CompatibilityResult] = []
+    has_failure = False
+
+    for proposed in proposed_contracts:
+        current = registry.get_latest_contract(proposed.product, proposed.model)
+        consumers = registry.list_consumers(proposed.product, proposed.model)
+
+        result = engine.compare_contracts(
+            current_contract=current,
+            proposed_contract=proposed,
+            consumers=consumers,
+        )
+        results.append(result)
+        if not result.is_compatible:
+            has_failure = True
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(results))
+    else:
+        reporter = ConsoleReporter()
+        reporter.render_compatibility_results(results)
+
+    if has_failure:
+        raise typer.Exit(code=1)
+
+    raise typer.Exit(code=0)

dbt_contracts/cli/consumer.py

@@ -0,0 +1,107 @@
+"""CLI subcommands for managing consumer expectations."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dbt_contracts.consumers.parser import ConsumerDeclarationParser
+from dbt_contracts.exceptions import ConsumerDeclarationError
+from dbt_contracts.registry.sqlite import SqliteContractRegistry
+from dbt_contracts.reporting.console import ConsoleReporter
+from dbt_contracts.reporting.json import render_json
+
+app = typer.Typer(help="Manage downstream consumer contract declarations.")
+
+
+@app.command("register")
+def register_consumer_command(
+    file_path: Annotated[
+        Path,
+        typer.Option(
+            "--file",
+            "-f",
+            help="Path to data-contract-consumers.yml declaration file.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = Path("data-contract-consumers.yml"),
+    registry_path: Annotated[
+        Path,
+        typer.Option(
+            "--registry",
+            "-r",
+            help="Path to SQLite contract registry database file.",
+        ),
+    ] = Path(".contracts.db"),
+    format_output: Annotated[
+        str,
+        typer.Option("--format", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """Parse a consumer declaration YAML file and register expectations in the registry."""
+    parser = ConsumerDeclarationParser()
+
+    try:
+        expectations = parser.parse_file(file_path)
+    except ConsumerDeclarationError as e:
+        typer.secho(f"Error parsing consumer declarations: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from e
+
+    registry = SqliteContractRegistry(db_path=registry_path)
+    for exp in expectations:
+        registry.register_consumer(exp)
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(expectations))
+    else:
+        reporter = ConsoleReporter()
+        typer.secho(
+            f"Successfully registered {len(expectations)} expectation(s) in {registry_path}:",
+            fg=typer.colors.GREEN,
+        )
+        reporter.render_consumers_list(expectations)
+
+
+@app.command("list")
+def list_consumers_command(
+    registry_path: Annotated[
+        Path,
+        typer.Option(
+            "--registry",
+            "-r",
+            help="Path to SQLite contract registry database file.",
+        ),
+    ] = Path(".contracts.db"),
+    product: Annotated[
+        str | None,
+        typer.Option("--product", "-p", help="Filter by target product name."),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", "-m", help="Filter by target model name."),
+    ] = None,
+    format_output: Annotated[
+        str,
+        typer.Option("--format", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """List registered consumer expectations."""
+    registry = SqliteContractRegistry(db_path=registry_path)
+
+    if product and model:
+        consumers = registry.list_consumers(product, model)
+    else:
+        consumers = registry.list_all_consumers()
+        if product:
+            consumers = [c for c in consumers if c.product == product]
+        if model:
+            consumers = [c for c in consumers if c.model == model]
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(consumers))
+    else:
+        reporter = ConsoleReporter()
+        reporter.render_consumers_list(consumers)

dbt_contracts/cli/ingest.py

@@ -0,0 +1,64 @@
+"""CLI command for ingesting and inspecting dbt manifests."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dbt_contracts.dbt.ingestion import DbtManifestIngestor
+from dbt_contracts.exceptions import ManifestParseError
+from dbt_contracts.reporting.console import ConsoleReporter
+from dbt_contracts.reporting.json import render_json
+
+app = typer.Typer(help="Ingest and inspect dbt artifacts.")
+
+
+@app.callback(invoke_without_command=True)
+def ingest_command(
+    manifest: Annotated[
+        Path,
+        typer.Option(
+            "--manifest",
+            "-m",
+            help="Path to dbt manifest.json file.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = Path("target/manifest.json"),
+    version: Annotated[
+        str | None,
+        typer.Option("--version", "-v", help="Override contract version for discovered models."),
+    ] = None,
+    product: Annotated[
+        str | None,
+        typer.Option("--product", "-p", help="Override data product name for discovered models."),
+    ] = None,
+    all_models: Annotated[
+        bool,
+        typer.Option("--all", "-a", help="Include all models, not just public models."),
+    ] = False,
+    format_output: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """Ingest a dbt manifest.json and print discovered public contracts."""
+    ingestor = DbtManifestIngestor(include_all_models=all_models)
+
+    try:
+        contracts = ingestor.parse_manifest_file(
+            manifest_path=manifest,
+            version_override=version,
+            product_override=product,
+        )
+    except ManifestParseError as e:
+        typer.secho(f"Error parsing manifest: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from e
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(contracts))
+    else:
+        reporter = ConsoleReporter()
+        reporter.render_contracts_list(contracts)

dbt_contracts/cli/publish.py

@@ -0,0 +1,97 @@
+"""CLI command for publishing contracts to the registry."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dbt_contracts.dbt.ingestion import DbtManifestIngestor
+from dbt_contracts.exceptions import ContractAlreadyPublishedError, DbtContractsError
+from dbt_contracts.registry.sqlite import SqliteContractRegistry
+from dbt_contracts.reporting.console import ConsoleReporter
+from dbt_contracts.reporting.json import render_json
+
+app = typer.Typer(help="Publish contracts to the registry.")
+
+
+@app.callback(invoke_without_command=True)
+def publish_command(
+    manifest: Annotated[
+        Path,
+        typer.Option(
+            "--manifest",
+            "-m",
+            help="Path to dbt manifest.json file.",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = Path("target/manifest.json"),
+    registry_path: Annotated[
+        Path,
+        typer.Option(
+            "--registry",
+            "-r",
+            help="Path to SQLite contract registry database file.",
+        ),
+    ] = Path(".contracts.db"),
+    version: Annotated[
+        str | None,
+        typer.Option("--version", "-v", help="Contract version to publish (e.g. 1.0.0)."),
+    ] = None,
+    product: Annotated[
+        str | None,
+        typer.Option("--product", "-p", help="Data product name override."),
+    ] = None,
+    all_models: Annotated[
+        bool,
+        typer.Option("--all", "-a", help="Publish all models, not just public models."),
+    ] = False,
+    format_output: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """Ingest dbt manifest and publish contracts to the registry."""
+    ingestor = DbtManifestIngestor(
+        default_version=version or "1.0.0", include_all_models=all_models
+    )
+
+    try:
+        contracts = ingestor.parse_manifest_file(
+            manifest_path=manifest,
+            version_override=version,
+            product_override=product,
+        )
+    except DbtContractsError as e:
+        typer.secho(f"Error parsing manifest: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from e
+
+    if not contracts:
+        typer.secho("No public contracts found to publish.", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=0)
+
+    registry = SqliteContractRegistry(db_path=registry_path)
+
+    published_contracts = []
+    for contract in contracts:
+        try:
+            registry.publish_contract(contract)
+            published_contracts.append(contract)
+        except ContractAlreadyPublishedError as e:
+            typer.secho(f"Publication failed: {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from e
+        except Exception as e:
+            typer.secho(f"Registry error: {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=2) from e
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(published_contracts))
+    else:
+        reporter = ConsoleReporter()
+        typer.secho(
+            f"Successfully published {len(published_contracts)} contract(s) to {registry_path}:",
+            fg=typer.colors.GREEN,
+        )
+        reporter.render_contracts_list(published_contracts)

dbt_contracts/cli/registry.py

@@ -0,0 +1,62 @@
+"""CLI subcommands for querying the contract registry."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dbt_contracts.registry.sqlite import SqliteContractRegistry
+from dbt_contracts.reporting.console import ConsoleReporter
+from dbt_contracts.reporting.json import render_json
+
+app = typer.Typer(help="Inspect published contracts in the registry.")
+
+
+@app.command("list")
+def list_contracts_command(
+    registry_path: Annotated[
+        Path,
+        typer.Option(
+            "--registry",
+            "-r",
+            help="Path to SQLite contract registry database file.",
+        ),
+    ] = Path(".contracts.db"),
+    product: Annotated[
+        str | None,
+        typer.Option("--product", "-p", help="Filter by product name."),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", "-m", help="Filter by model name."),
+    ] = None,
+    all_versions: Annotated[
+        bool,
+        typer.Option("--all-versions", "-a", help="List all historical versions, not just latest."),
+    ] = False,
+    format_output: Annotated[
+        str,
+        typer.Option("--format", help="Output format ('console' or 'json')."),
+    ] = "console",
+) -> None:
+    """List contracts published in the registry."""
+    registry = SqliteContractRegistry(db_path=registry_path)
+
+    if product and model:
+        if all_versions:
+            contracts = registry.list_contract_versions(product, model)
+        else:
+            latest = registry.get_latest_contract(product, model)
+            contracts = [latest] if latest else []
+    else:
+        contracts = registry.list_all_contracts()
+        if product:
+            contracts = [c for c in contracts if c.product == product]
+        if model:
+            contracts = [c for c in contracts if c.model == model]
+
+    if format_output.lower() == "json":
+        typer.echo(render_json(contracts))
+    else:
+        reporter = ConsoleReporter()
+        reporter.render_contracts_list(contracts)

dbt_contracts/compatibility/__init__.py

@@ -0,0 +1,11 @@
+"""SemVer compatibility engine and rules."""
+
+from dbt_contracts.compatibility.engine import CompatibilityEngine
+from dbt_contracts.compatibility.types import TypeFamily, are_types_compatible, normalize_type_name
+
+__all__ = [
+    "CompatibilityEngine",
+    "TypeFamily",
+    "are_types_compatible",
+    "normalize_type_name",
+]

dbt_contracts/compatibility/engine.py

@@ -0,0 +1,119 @@
+"""Compatibility engine orchestrating contract diffing and SemVer enforcement."""
+
+from dbt_contracts.compatibility.rules.columns import evaluate_column_changes
+from dbt_contracts.compatibility.rules.consumers import evaluate_consumer_impact
+from dbt_contracts.compatibility.rules.metadata import evaluate_metadata_changes
+from dbt_contracts.compatibility.rules.nullability import evaluate_nullability_changes
+from dbt_contracts.domain.compatibility import (
+    BreakingChange,
+    CompatibilityClassification,
+    CompatibilityResult,
+)
+from dbt_contracts.domain.consumers import ConsumerExpectation
+from dbt_contracts.domain.contracts import PublishedContract
+from dbt_contracts.domain.versions import validate_version_bump
+
+
+class CompatibilityEngine:
+    """Evaluates compatibility between contract versions and registered consumers."""
+
+    def compare_contracts(
+        self,
+        current_contract: PublishedContract | None,
+        proposed_contract: PublishedContract,
+        consumers: list[ConsumerExpectation] | None = None,
+    ) -> CompatibilityResult:
+        """Compare a current contract against a proposed contract and evaluate consumer impact."""
+        consumers = consumers or []
+        breaking_changes: list[BreakingChange] = []
+        reasons: list[str] = []
+        warnings: list[str] = []
+
+        # Case 1: Brand new contract publication (no previous contract)
+        if current_contract is None:
+            reasons.append("Initial contract publication.")
+            # Evaluate against any pre-registered consumers
+            affected, consumer_warnings = evaluate_consumer_impact(
+                proposed_contract, consumers, breaking_changes
+            )
+            warnings.extend(consumer_warnings)
+
+            return CompatibilityResult(
+                product=proposed_contract.product,
+                model=proposed_contract.model,
+                current_version=None,
+                proposed_version=proposed_contract.version,
+                classification=CompatibilityClassification.PATCH,
+                is_valid_bump=True,
+                breaking_changes=[],
+                affected_consumers=affected,
+                reasons=reasons,
+                warnings=warnings,
+                suggested_min_version=proposed_contract.version,
+            )
+
+        # Case 2: Comparing against existing contract version
+        # 1. Column changes
+        col_class, col_breaking, col_reasons = evaluate_column_changes(
+            current_contract, proposed_contract
+        )
+        breaking_changes.extend(col_breaking)
+        reasons.extend(col_reasons)
+
+        # 2. Nullability changes
+        null_class, null_breaking, null_reasons = evaluate_nullability_changes(
+            current_contract, proposed_contract
+        )
+        breaking_changes.extend(null_breaking)
+        reasons.extend(null_reasons)
+
+        # 3. Metadata changes
+        _, meta_reasons = evaluate_metadata_changes(current_contract, proposed_contract)
+        reasons.extend(meta_reasons)
+
+        # Determine raw classification based on severity rank
+        max_rank = max(
+            col_class.severity_rank,
+            null_class.severity_rank,
+        )
+
+        rank_to_class = {
+            1: CompatibilityClassification.PATCH,
+            2: CompatibilityClassification.MINOR,
+            3: CompatibilityClassification.MAJOR,
+            4: CompatibilityClassification.UNKNOWN,
+        }
+        classification = rank_to_class.get(max_rank, CompatibilityClassification.MAJOR)
+
+        # 4. Consumer impact evaluation
+        affected_consumers, consumer_warnings = evaluate_consumer_impact(
+            proposed_contract, consumers, breaking_changes
+        )
+        warnings.extend(consumer_warnings)
+
+        if affected_consumers:
+            classification = CompatibilityClassification.MAJOR
+            reasons.append(
+                f"{len(affected_consumers)} registered consumer expectation(s) affected."
+            )
+
+        # 5. SemVer version bump validation
+        is_valid_bump, suggested_min_v = validate_version_bump(
+            current_contract.version,
+            proposed_contract.version,
+            classification,
+        )
+
+        return CompatibilityResult(
+            product=proposed_contract.product,
+            model=proposed_contract.model,
+            current_version=current_contract.version,
+            proposed_version=proposed_contract.version,
+            classification=classification,
+            is_valid_bump=is_valid_bump,
+            breaking_changes=breaking_changes,
+            affected_consumers=affected_consumers,
+            reasons=reasons,
+            warnings=warnings,
+            suggested_min_version=suggested_min_v,
+        )