specdbt 0.1.0__py3-none-any.whl

specdbt/adapters/base.py

@@ -0,0 +1,39 @@
+"""Execution adapter interface — the engine-agnostic boundary. Every concrete
+adapter (FakeAdapter now; PolarsAdapter/DuckDBAdapter/DbtCoreAdapter later)
+implements this and nothing above it needs to know which one is in use.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from specdbt.fixtures import Fixture
+
+
+@dataclass
+class ExecutionResult:
+    rows: list[dict]
+    row_count: int
+    raw: object = None
+
+    @classmethod
+    def of(cls, rows: list[dict], raw: object = None) -> ExecutionResult:
+        """Convenience constructor: row_count is derived from len(rows)."""
+        return cls(rows=rows, row_count=len(rows), raw=raw)
+
+
+class ExecutionAdapter(ABC):
+    @abstractmethod
+    def run_model(self, model_name: str, fixtures: list[Fixture]) -> ExecutionResult:
+        """Run `model_name` with the given fixtures substituted for its
+        refs/sources, and return the resulting rows."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def run_macro(self, macro_call: str, fixtures: list[Fixture]) -> ExecutionResult:
+        """Run `macro_call` -- a complete, real Jinja/SQL query string (not
+        just a macro call expression), with the given fixtures'
+        ref()/source() substituted for their ephemeral relations -- and
+        return the resulting rows."""
+        raise NotImplementedError

specdbt/adapters/dbt_adapter.py

@@ -0,0 +1,111 @@
+"""Real execution against whatever dbt target a project's profile points at,
+via dbtRunner -- the only concrete ExecutionAdapter that computes real
+results instead of returning canned ones."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from dbt.cli.main import dbtRunner
+
+from specdbt.adapters.base import ExecutionAdapter, ExecutionResult
+from specdbt.adapters.prod_guard import (  # noqa: F401 -- re-exported for tests/test_dbt_adapter.py
+    ProdSchemaGuardError,
+    guard_against_prod_target,
+)
+from specdbt.dbt_integration.fixture_sql import render_fixture_ctas
+from specdbt.dbt_integration.macro_file import (
+    delete_macro_file,
+    render_macro_file,
+    setup_macro_name,
+    teardown_macro_name,
+    write_macro_file,
+)
+from specdbt.dbt_integration.ref_substitution import substitute_fixture_refs
+from specdbt.dbt_integration.target_catalog import resolve_target_catalog
+from specdbt.fixtures import Fixture
+
+
+class DbtInvocationError(RuntimeError):
+    """Raised when a dbtRunner.invoke() call fails."""
+
+
+class ModelIntegrationTierNotImplementedError(NotImplementedError):
+    """Raised by run_model. The macro-file substitution mechanism only
+    works because a macro call's ref()/source() arguments are text
+    specdbt's own call site controls. A model's ref()s are inside its own
+    SQL file, which this mechanism never touches -- running it for real
+    would use whatever real state those refs already resolve to, not the
+    scenario's fixtures, silently producing wrong results."""
+
+
+class DbtExecutionAdapter(ExecutionAdapter):
+    def __init__(
+        self,
+        project_dir: Path,
+        profiles_dir: Path,
+        *,
+        target: str | None = None,
+        allow_any_schema: bool = False,
+        keep_schema: bool = False,
+    ) -> None:
+        guard_against_prod_target(target, allow_any_schema)
+        self._project_dir = Path(project_dir)
+        self._profiles_dir = Path(profiles_dir)
+        self._target = target
+        self._keep_schema = keep_schema
+        self._runner = dbtRunner()
+
+    def run_model(self, model_name: str, fixtures: list[Fixture]) -> ExecutionResult:
+        raise ModelIntegrationTierNotImplementedError(
+            f"DbtExecutionAdapter.run_model({model_name!r}) is not "
+            "implemented -- model integration-tier testing goes through "
+            "FakeAdapter or the unit tier instead."
+        )
+
+    def run_macro(self, macro_call: str, fixtures: list[Fixture]) -> ExecutionResult:
+        database = resolve_target_catalog(self._project_dir, self._profiles_dir, self._target)
+        run_id = uuid.uuid4().hex
+        schema = f"specdbt_{run_id}"
+        fixture_names = {fixture.name for fixture in fixtures}
+        substituted_call = substitute_fixture_refs(
+            macro_call, schema, fixture_names, database=database
+        )
+        fixture_ctas = [
+            render_fixture_ctas(schema, fixture, database=database) for fixture in fixtures
+        ]
+        macro_text = render_macro_file(run_id, schema, fixture_ctas, database=database)
+        macro_path = write_macro_file(self._project_dir, run_id, macro_text)
+
+        try:
+            self._invoke(["run-operation", setup_macro_name(run_id)])
+            show_result = self._invoke(
+                ["show", "--inline", substituted_call, "--output", "json", "--limit", "-1"]
+            )
+            agate_table = show_result.result.results[0].agate_table
+            rows = [
+                dict(zip(agate_table.column_names, row, strict=True)) for row in agate_table.rows
+            ]
+            return ExecutionResult.of(rows)
+        finally:
+            if not self._keep_schema:
+                self._invoke(["run-operation", teardown_macro_name(run_id)])
+                delete_macro_file(macro_path)
+
+    def _invoke(self, args: list[str]):
+        full_args = [
+            *args,
+            "--project-dir",
+            str(self._project_dir),
+            "--profiles-dir",
+            str(self._profiles_dir),
+            "--quiet",
+            "--no-send-anonymous-usage-stats",
+        ]
+        if self._target:
+            full_args += ["--target", self._target]
+        result = self._runner.invoke(full_args)
+        if not result.success:
+            raise DbtInvocationError(f"dbt {args[0]} failed: {result.exception}")
+        return result

specdbt/adapters/fake_adapter.py

@@ -0,0 +1,38 @@
+"""Phase 0's only concrete adapter: returns pre-registered canned results,
+never computes anything from the fixtures it's given. Proves the pipeline
+plumbing; DbtExecutionAdapter (Phase 1) provides real correctness for macros.
+"""
+
+from __future__ import annotations
+
+from specdbt.adapters.base import ExecutionAdapter, ExecutionResult
+from specdbt.fixtures import Fixture
+
+
+class ModelNotRegisteredError(KeyError):
+    """Raised when run_model()/run_macro() is asked for a name with no
+    canned result registered."""
+
+
+class FakeAdapter(ExecutionAdapter):
+    def __init__(self) -> None:
+        self._canned_results: dict[str, ExecutionResult] = {}
+
+    def register(self, name: str, result: ExecutionResult) -> None:
+        """Registers a canned result under `name` -- a model name
+        (run_model) or the exact macro-call string a scenario's When step
+        uses (run_macro). Same registry either way; FakeAdapter doesn't
+        distinguish between the two kinds of caller."""
+        self._canned_results[name] = result
+
+    def run_model(self, model_name: str, fixtures: list[Fixture]) -> ExecutionResult:
+        return self._lookup(model_name)
+
+    def run_macro(self, macro_call: str, fixtures: list[Fixture]) -> ExecutionResult:
+        return self._lookup(macro_call)
+
+    def _lookup(self, name: str) -> ExecutionResult:
+        try:
+            return self._canned_results[name]
+        except KeyError:
+            raise ModelNotRegisteredError(f"no canned result registered for {name!r}") from None

specdbt/adapters/prod_guard.py

@@ -0,0 +1,22 @@
+"""Shared prod-schema heuristic guard -- used by every real-execution path
+that touches a dbt target: DbtExecutionAdapter (macro/model integration
+tier, ephemeral) and ModelUnitTestCompiler (model unit tier -- its
+prebuild step writes real tables into the project's actually-configured
+schema, not an ephemeral one, so it needs the same guard).
+"""
+
+from __future__ import annotations
+
+
+class ProdSchemaGuardError(RuntimeError):
+    """Raised when the configured target name looks like production and
+    allow_any_schema was not passed."""
+
+
+def guard_against_prod_target(target: str | None, allow_any_schema: bool) -> None:
+    if target and "prod" in target.lower() and not allow_any_schema:
+        raise ProdSchemaGuardError(
+            f"target {target!r} looks like production -- refusing to run. "
+            "Pass allow_any_schema=True (CLI: --allow-any-schema) if this "
+            "is really what you want."
+        )

specdbt/ai/stubs.py

@@ -0,0 +1,29 @@
+"""Typed placeholders for a future AI layer. Nothing here executes; this
+only fixes the package shape now so that layer is additive later, not a
+restructure."""
+
+from __future__ import annotations
+
+_NOT_YET = "AI features ship in Phase 3 -- see the roadmap doc."
+
+
+class LLMClient:
+    """Placeholder for the provider-agnostic LLM client (Phase 3)."""
+
+    def complete(self, prompt: str) -> str:
+        raise NotImplementedError(_NOT_YET)
+
+
+def generate_fixtures(model_sql: str, schema: dict[str, str], count: int = 3) -> list[dict]:
+    """Fixture synthesis (Phase 3, 03-ai-integration-plan.md §1)."""
+    raise NotImplementedError(_NOT_YET)
+
+
+def scenario_from_text(description: str) -> str:
+    """Natural-language -> Gherkin (Phase 3, 03-ai-integration-plan.md §2)."""
+    raise NotImplementedError(_NOT_YET)
+
+
+def explain_failure(fixture: dict, model_sql: str, diff: dict) -> str:
+    """Failure triage (Phase 3, 03-ai-integration-plan.md §4)."""
+    raise NotImplementedError(_NOT_YET)

specdbt/assertions.py

@@ -0,0 +1,145 @@
+"""Then-step assertion library."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+import polars as pl
+
+from specdbt.adapters.base import ExecutionResult
+from specdbt.typing_utils import coerce_scalar, rows_from_data_table
+
+
+class AssertionFailure(AssertionError):
+    def __init__(self, message: str, expected: object = None, actual: object = None) -> None:
+        super().__init__(message)
+        self.expected = expected
+        self.actual = actual
+
+
+class UnrecognizedStepError(ValueError):
+    """Raised when a Then/And/But step's text matches none of the known patterns."""
+
+
+PRODUCES_ROWS_RE = re.compile(r'the "(.+)" should produce the following rows:$')
+_ROW_COUNT_RE = re.compile(r'^"([^"]+)" should have (\d+) rows?$')
+_NOT_NULL_RE = re.compile(r'^column "([^"]+)" in "([^"]+)" should not contain nulls$')
+_UNIQUE_RE = re.compile(r'^column "([^"]+)" in "([^"]+)" should be unique$')
+_ROW_FIELD_RE = re.compile(r'^the row for (\w+) "([^"]+)" should have (\w+) (.+)$')
+
+
+@dataclass
+class ThenContext:
+    """What a Then/And/But step needs: every named result produced so far in the
+    scenario, and the most recently produced one (for steps that don't name a
+    model explicitly, like "the row for X should have Y")."""
+
+    results: dict[str, ExecutionResult]
+    last_model: str | None
+
+
+def evaluate_then_step(text: str, ctx: ThenContext, table: list[list[str]] | None = None) -> None:
+    """Raise AssertionFailure if the expectation doesn't hold, or
+    UnrecognizedStepError if the text matches no known pattern. None on
+    success. `table` is the step's data table, if it has one -- only the
+    row-table form (the canonical Then) uses it."""
+    if (m := PRODUCES_ROWS_RE.match(text)) is not None:
+        name = m.group(1)
+        if not table:
+            raise AssertionFailure(f"{text!r} requires a data table of expected rows")
+        result = _lookup(ctx, name)
+        header = table[0]
+        expected_rows = rows_from_data_table(table)
+        projected_actual_rows = [
+            {column: row.get(column) for column in header} for row in result.rows
+        ]
+        expected_counts = Counter(tuple(row[c] for c in header) for row in expected_rows)
+        actual_counts = Counter(tuple(row[c] for c in header) for row in projected_actual_rows)
+        if actual_counts != expected_counts:
+            expected_df = pl.DataFrame(expected_rows) if expected_rows else pl.DataFrame()
+            actual_df = (
+                pl.DataFrame(projected_actual_rows) if projected_actual_rows else pl.DataFrame()
+            )
+            raise AssertionFailure(
+                f'"{name}" produced different rows than expected (only columns '
+                f"{header} are compared; row order doesn't matter, row count "
+                f"does):\n"
+                f"--- expected ---\n{expected_df}\n"
+                f"--- actual (projected) ---\n{actual_df}",
+                expected=expected_rows,
+                actual=projected_actual_rows,
+            )
+        return
+
+    if (m := _ROW_COUNT_RE.match(text)) is not None:
+        model_name, expected_count = m.group(1), int(m.group(2))
+        result = _lookup(ctx, model_name)
+        if result.row_count != expected_count:
+            raise AssertionFailure(
+                f'expected "{model_name}" to have {expected_count} row(s), got {result.row_count}',
+                expected=expected_count,
+                actual=result.row_count,
+            )
+        return
+
+    if (m := _NOT_NULL_RE.match(text)) is not None:
+        column, model_name = m.group(1), m.group(2)
+        result = _lookup(ctx, model_name)
+        nulls = [row for row in result.rows if row.get(column) is None]
+        if nulls:
+            raise AssertionFailure(
+                f'expected column "{column}" in "{model_name}" to contain no nulls, '
+                f"found {len(nulls)}",
+                expected="no nulls",
+                actual=f"{len(nulls)} null row(s)",
+            )
+        return
+
+    if (m := _UNIQUE_RE.match(text)) is not None:
+        column, model_name = m.group(1), m.group(2)
+        result = _lookup(ctx, model_name)
+        values = [row.get(column) for row in result.rows]
+        duplicates = sorted({v for v in values if values.count(v) > 1}, key=str)
+        if duplicates:
+            raise AssertionFailure(
+                f'expected column "{column}" in "{model_name}" to be unique, '
+                f"found duplicate(s) {duplicates}",
+                expected="unique values",
+                actual=f"duplicates: {duplicates}",
+            )
+        return
+
+    if (m := _ROW_FIELD_RE.match(text)) is not None:
+        key_col, key_val_raw, field_name, raw_value = m.groups()
+        if ctx.last_model is None:
+            raise AssertionFailure(f"no model has run yet to check a row against: {text!r}")
+        result = _lookup(ctx, ctx.last_model)
+        key_val = coerce_scalar(key_val_raw)
+        matches = [row for row in result.rows if row.get(key_col) == key_val]
+        if not matches:
+            raise AssertionFailure(
+                f'no row found where {key_col} == {key_val_raw!r} in "{ctx.last_model}"',
+                expected=f"a row with {key_col}={key_val_raw!r}",
+                actual="no matching row",
+            )
+        expected_value = coerce_scalar(raw_value.strip('"'))
+        actual_value = matches[0].get(field_name)
+        if actual_value != expected_value:
+            raise AssertionFailure(
+                f"expected {field_name} {expected_value!r} for row {key_col}={key_val_raw!r}, "
+                f"got {actual_value!r}",
+                expected=expected_value,
+                actual=actual_value,
+            )
+        return
+
+    raise UnrecognizedStepError(f"no assertion pattern matches: {text!r}")
+
+
+def _lookup(ctx: ThenContext, model_name: str) -> ExecutionResult:
+    try:
+        return ctx.results[model_name]
+    except KeyError:
+        raise AssertionFailure(f'model "{model_name}" has not run yet in this scenario') from None

specdbt/cli.py

@@ -0,0 +1,168 @@
+"""specdbt command-line interface."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import click
+
+from specdbt.adapters.base import ExecutionResult
+from specdbt.adapters.dbt_adapter import DbtExecutionAdapter
+from specdbt.adapters.fake_adapter import FakeAdapter
+from specdbt.native_unit_tests.compiler import CompilerRegistry
+from specdbt.native_unit_tests.model_unit_test_compiler import ModelUnitTestCompiler
+from specdbt.reporter import render_feature_report, render_summary
+from specdbt.runner import run_feature_file
+
+_SCAFFOLD_FEATURE = """Feature: Example feature
+
+  Scenario: Replace this with a real scenario
+    Given the following rows in "example_source":
+      | id | value |
+      | 1  | hello |
+    When the "example_model" model runs
+    Then "example_model" should have 1 row
+"""
+
+_SCAFFOLD_CANNED = '''"""Hand-coded canned result for example.feature (Phase 0)."""
+from specdbt.adapters.base import ExecutionResult
+
+CANNED_RESULTS = {
+    "example_model": ExecutionResult.of(rows=[{"id": 1, "value": "hello"}]),
+}
+'''
+
+
+@click.group()
+def cli() -> None:
+    """specdbt -- BDD-style Given/When/Then testing for dbt models."""
+
+
+@cli.command()
+@click.argument("directory", type=click.Path(path_type=Path), default=Path("features"))
+def init(directory: Path) -> None:
+    """Scaffold DIRECTORY with one example .feature file and its canned result."""
+    directory.mkdir(parents=True, exist_ok=True)
+    example = directory / "example.feature"
+    canned = example.with_suffix(".canned.py")
+    if example.exists() or canned.exists():
+        raise click.ClickException(f"{example} already exists, not overwriting")
+    example.write_text(_SCAFFOLD_FEATURE)
+    canned.write_text(_SCAFFOLD_CANNED)
+    click.echo(f"created {example}")
+    click.echo(f"created {canned}")
+
+
+def _load_canned_results(path: Path) -> dict[str, ExecutionResult]:
+    spec = importlib.util.spec_from_file_location(f"_specdbt_canned_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise click.ClickException(f"could not load {path} as a Python module")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    try:
+        return module.CANNED_RESULTS
+    except AttributeError:
+        raise click.ClickException(f"{path} does not define CANNED_RESULTS") from None
+
+
+@cli.command()
+@click.argument("target", type=click.Path(path_type=Path, exists=True))
+@click.option(
+    "--engine",
+    type=click.Choice(["fake", "dbt"]),
+    default="fake",
+    help="fake (default): FakeAdapter + co-located .canned.py. "
+    "dbt: DbtExecutionAdapter, real execution.",
+)
+@click.option("--project-dir", "project_dir", type=click.Path(path_type=Path, exists=True))
+@click.option("--profiles-dir", "profiles_dir", type=click.Path(path_type=Path, exists=True))
+@click.option("--target", "dbt_target", default=None)
+@click.option("--allow-any-schema", is_flag=True, default=False)
+@click.option("--keep-schema", is_flag=True, default=False)
+def run(
+    target: Path,
+    engine: str,
+    project_dir: Path | None,
+    profiles_dir: Path | None,
+    dbt_target: str | None,
+    allow_any_schema: bool,
+    keep_schema: bool,
+) -> None:
+    """Parse and run the .feature file(s) under TARGET.
+
+    --engine fake (default): each FEATURE.feature file may have a co-located
+    FEATURE.canned.py exposing CANNED_RESULTS: dict[str, ExecutionResult],
+    pre-registered into a fresh FakeAdapter before that file's scenarios run.
+
+    --engine dbt: real execution via DbtExecutionAdapter against --project-dir
+    (required) and --profiles-dir (defaults to --project-dir).
+    """
+    paths = sorted(target.rglob("*.feature")) if target.is_dir() else [target]
+    if not paths:
+        raise click.ClickException(f"no .feature files found under {target}")
+
+    dbt_adapter: DbtExecutionAdapter | None = None
+    compiler_registry: CompilerRegistry | None = None
+    if engine == "dbt":
+        if project_dir is None:
+            raise click.ClickException("--project-dir is required with --engine dbt")
+        dbt_adapter = DbtExecutionAdapter(
+            project_dir=project_dir,
+            profiles_dir=profiles_dir or project_dir,
+            target=dbt_target,
+            allow_any_schema=allow_any_schema,
+            keep_schema=keep_schema,
+        )
+        compiler_registry = CompilerRegistry()
+        compiler_registry.register(
+            "model",
+            ModelUnitTestCompiler(
+                project_dir=project_dir,
+                profiles_dir=profiles_dir or project_dir,
+                target=dbt_target,
+                allow_any_schema=allow_any_schema,
+            ),
+        )
+
+    reports = []
+    for path in paths:
+        if dbt_adapter is not None:
+            adapter = dbt_adapter
+        else:
+            adapter = FakeAdapter()
+            canned_path = path.with_suffix(".canned.py")
+            if canned_path.exists():
+                for model_name, result in _load_canned_results(canned_path).items():
+                    adapter.register(model_name, result)
+        reports.append(run_feature_file(path, adapter, compiler_registry))
+
+    for report in reports:
+        click.echo(render_feature_report(report))
+    click.echo(render_summary(reports))
+
+    if any(not scenario.passed for report in reports for scenario in report.scenarios):
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("--from-model", "from_model", required=True)
+@click.option("--fixtures", "fixtures_flag", is_flag=True, default=False)
+def generate(from_model: str, fixtures_flag: bool) -> None:
+    """AI-assisted scenario/fixture generation (Phase 3 -- not implemented yet)."""
+    raise click.ClickException(
+        "`specdbt generate` ships in Phase 3 -- see the AI integration plan doc."
+    )
+
+
+@cli.command(name="compile")
+@click.argument("target", type=click.Path(path_type=Path, exists=True))
+@click.option("--to", "to_format", type=click.Choice(["dbt-unit-tests"]), required=True)
+def compile_(target: Path, to_format: str) -> None:
+    """Compile .feature scenarios to native dbt unit tests (Phase 2 -- not implemented yet)."""
+    raise click.ClickException("`specdbt compile` ships in Phase 2 -- see the roadmap doc.")
+
+
+if __name__ == "__main__":
+    cli()

specdbt/dbt_integration/fixture_sql.py

@@ -0,0 +1,56 @@
+"""Render a Fixture as a CREATE TABLE ... AS SELECT ... UNION ALL statement,
+for real execution against a dbt target.
+
+Column types are Python-value-derived (the only information available --
+many fixture names aren't real manifest nodes, so
+adapter.get_columns_in_relation isn't usable for the common case), but made
+explicit and adapter-dispatched via dbt.cast(...) + a per-column dbt type
+macro, instead of relying on implicit VALUES-clause type inference --
+which is not guaranteed identical across engines (an all-NULL column,
+mixed int/float precision). dbt.cast, not dbt.safe_cast: some adapters
+implement safe_cast as a silently-NULL-on-failure try_cast, wrong for a
+testing framework, which should fail loudly on a type mismatch. The
+`select ... union all select ...` shape matches dbt-core's own native
+unit-test fixture generator, avoiding VALUES's cross-engine column-aliasing
+and implicit-coercion quirks (spec: macro-tier adapter-dispatch design,
+2026-08-30).
+"""
+
+from __future__ import annotations
+
+from specdbt.dbt_integration.relation_expr import relation_expr
+from specdbt.fixtures import Fixture
+from specdbt.sql_literals import sql_literal_expr
+
+
+def _dbt_type_macro(values: list) -> str:
+    if any(isinstance(v, float) for v in values):
+        return "dbt.type_float()"
+    if any(isinstance(v, str) for v in values):
+        return "dbt.type_string()"
+    if any(isinstance(v, int) and not isinstance(v, bool) for v in values):
+        return "dbt.type_bigint()"
+    if any(isinstance(v, bool) for v in values):
+        return "dbt.type_boolean()"
+    return "dbt.type_string()"  # all-NULL column
+
+
+def render_fixture_ctas(schema: str, fixture: Fixture, *, database: str | None = None) -> str:
+    """`fixture.rows` must be non-empty -- fixtures.build_fixture already
+    enforces this via FixtureBuildError. Columns come from the first row's
+    key order; all rows in one fixture are assumed to share the same
+    columns, matching how the Gherkin data table they came from is shaped."""
+    columns = list(fixture.rows[0].keys())
+    column_types = {col: _dbt_type_macro([row[col] for row in fixture.rows]) for col in columns}
+
+    select_rows = [
+        "select "
+        + ", ".join(
+            f"{{{{ dbt.cast({sql_literal_expr(row[col])}, {column_types[col]}) }}}} as {col}"
+            for col in columns
+        )
+        for row in fixture.rows
+    ]
+    body = "\nunion all\n".join(select_rows)
+    relation = relation_expr(schema=schema, identifier=fixture.name, database=database)
+    return f"create table {{{{ {relation} }}}} as (\n{body}\n)"