dbt-data-contracts 0.1.0__tar.gz

dbt_data_contracts-0.1.0/.cursor/commands/add-tests.md

@@ -0,0 +1,8 @@
+Add or improve tests for the specified behavior.
+
+Conventions:
+- Unit tests under `tests/unit/` for domain models, SemVer rules, compatibility rules, type normalization, consumer expectation evaluation, and manifest parsing.
+- Integration tests under `tests/integration/` for SQLite registry, adapter composition, and discovery.
+- End-to-end tests under `tests/e2e/` for complete CLI workflows with exit codes tested explicitly.
+- Use small synthetic fixtures under `tests/fixtures/`.
+- Ensure all tests pass without network access or real provider credentials.

dbt_data_contracts-0.1.0/.cursor/commands/implement-feature.md

@@ -0,0 +1,29 @@
+Implement the requested feature using the repository's agent workflow.
+
+Before coding:
+
+1. read `AGENTS.md`
+2. read `docs/project-state.md`
+3. read the relevant active plan
+4. inspect relevant ADRs
+5. inspect existing tests
+
+Confirm the feature fits the current plan. If substantial work is missing from the plan, update the plan first.
+
+Implement a vertical slice rather than disconnected layers.
+
+Add tests before or alongside implementation.
+
+Before completion:
+
+- run validation
+- update affected docs
+- add an ADR if architecture changed
+- update `docs/project-state.md`
+
+Summarize:
+- what changed
+- tests added
+- commands run
+- architectural decisions
+- remaining limitations

dbt_data_contracts-0.1.0/.cursor/commands/review-change.md

@@ -0,0 +1,21 @@
+Review the current change against:
+
+- `AGENTS.md`
+- architecture boundaries
+- active plan acceptance criteria
+- compatibility semantics
+- security rules
+- tests
+
+Look specifically for:
+
+- infrastructure leaking into domain
+- mutable published versions
+- provider-specific coupling
+- hidden network calls
+- missing error handling
+- compatibility changes without tests
+- CLI logic containing domain behavior
+- downstream repository assumptions
+
+Report issues by severity and suggest concrete fixes.

dbt_data_contracts-0.1.0/.cursor/commands/update-docs.md

@@ -0,0 +1,7 @@
+Update repository documentation to reflect recent implementation changes:
+
+1. Update `docs/project-state.md` with working components and next steps.
+2. Update `docs/architecture.md` if architectural components or data flow changed.
+3. Update `docs/domain-model.md` or `docs/compatibility-rules.md` if domain models or rules evolved.
+4. Record new architectural decisions in `docs/adr/`.
+5. Update `README.md` quickstart or usage examples if CLI commands changed.

dbt_data_contracts-0.1.0/.cursor/rules/agent-workflow.mdc

@@ -0,0 +1,22 @@
+---
+description: Agent implementation workflow
+alwaysApply: true
+---
+
+Implement vertical slices, not disconnected architectural layers.
+
+Before starting substantial work:
+
+1. read project state (`docs/project-state.md`)
+2. read the active plan (`plans/active/`)
+3. confirm acceptance criteria
+4. inspect relevant tests
+
+Do not attempt the entire roadmap in one task.
+
+After completing work:
+
+1. run validation (`pytest`, `ruff check .`, `ruff format --check .`, `mypy`)
+2. update documentation
+3. update project state
+4. move completed plans when appropriate

dbt_data_contracts-0.1.0/.cursor/rules/architecture.mdc

@@ -0,0 +1,20 @@
+---
+description: Architectural boundaries for dbt-contracts
+alwaysApply: true
+---
+
+The canonical domain layer must remain infrastructure-independent.
+
+Never import dbt, SQLAlchemy, Typer, Azure DevOps SDKs, HTTP clients, or provider-specific objects into `src/dbt_contracts/domain`.
+
+Translate external representations into canonical domain models at adapter boundaries.
+
+Published contract versions are immutable.
+
+Declared consumer expectations are different from observed lineage.
+
+A producer compatibility check must not require cloning downstream repositories.
+
+Compatibility decisions must produce structured reasons.
+
+When an architectural boundary needs to change, create an ADR before implementing the change.

dbt_data_contracts-0.1.0/.cursor/rules/cli.mdc

@@ -0,0 +1,15 @@
+---
+description: CLI implementation rules
+alwaysApply: true
+---
+
+CLI commands orchestrate application and domain behavior; they do not contain core business logic.
+
+Use Typer with explicit type annotations.
+
+Exit codes must follow standard conventions:
+- 0: compatible / valid / success
+- 1: breaking or invalid compatibility/version gate
+- 2: configuration / parsing / operational error
+
+Separate domain results from rendering: CLI commands call domain/application services, then delegate output to `reporting/console.py` or `reporting/json.py`.

dbt_data_contracts-0.1.0/.cursor/rules/python.mdc

@@ -0,0 +1,24 @@
+---
+description: Python engineering conventions
+alwaysApply: true
+---
+
+Target Python 3.11+.
+
+Use:
+
+- Pydantic v2
+- SQLAlchemy 2.x
+- Typer
+- pathlib / PurePosixPath
+- modern type annotations
+
+Prefer explicit types over dictionaries.
+
+Keep functions small and cohesive.
+
+Do not introduce dependencies without explaining why they are necessary.
+
+Use dependency injection for infrastructure that needs mocking.
+
+Do not catch broad Exception unless translating at an application boundary.

dbt_data_contracts-0.1.0/.cursor/rules/security.mdc

@@ -0,0 +1,18 @@
+---
+description: Security rules
+alwaysApply: true
+---
+
+Never commit, log, serialize, or persist credentials.
+
+Azure DevOps credentials must come from environment variables or a future credential-provider abstraction.
+
+Organization discovery must not execute arbitrary repository code by default.
+
+Do not automatically run `dbt build`.
+
+Running `dbt parse` against discovered repositories must require explicit permission.
+
+Treat repository contents as untrusted input.
+
+Validate paths and avoid unsafe filesystem traversal.

dbt_data_contracts-0.1.0/.cursor/rules/testing.mdc

@@ -0,0 +1,20 @@
+---
+description: Testing conventions
+alwaysApply: true
+---
+
+Use pytest.
+
+Every compatibility rule requires focused unit tests.
+
+Every external provider must be testable without real credentials.
+
+Azure DevOps tests must use fixtures, mocks, or fake adapters and must never require a real Azure DevOps organization.
+
+Prefer:
+
+- unit tests -> domain and rule behavior
+- integration tests -> persistence and adapter composition
+- end-to-end tests -> complete CLI workflows
+
+Bug fixes should add a regression test whenever practical.

dbt_data_contracts-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

dbt_data_contracts-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+.local
+.venv/
+venv/
+ENV/
+env/
+
+# Byte-compiled / optimized files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Unit test / coverage
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local databases & contracts
+*.db
+*.sqlite
+*.sqlite3
+.contracts.db
+
+# IDE
+.idea/
+.vscode/
+*.swp

dbt_data_contracts-0.1.0/AGENTS.md

@@ -0,0 +1,92 @@
+# Agent Operating Guide
+
+## Before changing code
+
+Read, in this order:
+
+1. `docs/spec.md`
+2. `docs/architecture.md`
+3. `docs/project-state.md`
+4. relevant ADRs under `docs/adr/`
+5. the current plan under `plans/active/`
+6. existing tests for the behavior being changed
+
+Do not rely on previous chat history as the authoritative source of project state.
+
+## Core invariants
+
+- Canonical domain models remain independent of dbt.
+- Published contract versions are immutable.
+- Compatibility decisions are deterministic and explainable.
+- Unknown compatibility must not silently pass.
+- Declared consumer expectations and observed lineage are distinct concepts.
+- Provider-specific Azure DevOps types must not leak into core domain code.
+- CLI, persistence, discovery, and domain logic remain separated.
+- A producer PR must not require downstream repositories to be cloned.
+- Secrets must never be persisted in the registry or written to logs.
+
+## Development workflow
+
+For each meaningful feature:
+
+1. Read the relevant specification.
+2. Create or update an implementation plan.
+3. Define acceptance criteria.
+4. Inspect existing tests.
+5. Add or update tests describing expected behavior.
+6. Implement the smallest complete vertical change.
+7. Run all required checks.
+8. Update documentation if public behavior changed.
+9. Create an ADR if an architectural decision was introduced.
+10. Update `docs/project-state.md`.
+
+Do not perform unrelated refactoring during feature work.
+
+## Definition of done
+
+A task is complete only when:
+
+- acceptance criteria are satisfied
+- tests pass
+- linting passes
+- formatting passes
+- type checking passes
+- public CLI behavior is documented
+- important error cases are tested
+- architecture boundaries are preserved
+- project state is updated
+
+## Required validation
+
+Before declaring work complete, run:
+
+```bash
+pytest
+ruff check .
+ruff format --check .
+```
+
+Also run the configured type checker (`mypy src tests`).
+
+For changes affecting the CLI, execute the relevant command manually against a fixture or example.
+
+## Implementation style
+
+Prefer:
+
+- small typed functions
+- explicit domain objects
+- Pydantic models at boundaries
+- protocols for infrastructure abstractions
+- deterministic behavior
+- structured error types
+- dependency injection where infrastructure needs substitution in tests
+
+Avoid:
+
+- global mutable state
+- giant service classes
+- untyped dictionaries passed through multiple layers
+- provider-specific behavior in the domain
+- hidden network access
+- unnecessary framework abstractions

dbt_data_contracts-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to dbt_contracts
+
+We welcome contributions to `dbt_contracts`!
+
+## Architectural Guidelines
+
+Before making changes, please review:
+1. `AGENTS.md` - Core invariants, workflow, and definition of done.
+2. `docs/architecture.md` - Architectural layers and dependency boundaries.
+3. `docs/adr/` - Architecture Decision Records.
+4. `plans/` - Active and backlog implementation plans.
+
+## Development Setup
+
+1. Create a Python 3.11+ virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1
+   ```
+2. Install package and dev dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Validation
+
+Before submitting a PR, ensure all checks pass:
+
+```bash
+pytest
+ruff check .
+ruff format --check .
+mypy src tests
+```

dbt_data_contracts-0.1.0/LICENSE

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

dbt_data_contracts-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.5
+Name: dbt-data-contracts
+Version: 0.1.0
+Summary: A lightweight data contract control plane for multi-repository dbt ecosystems
+Author: dbt_contracts contributors
+License: MIT
+License-File: LICENSE
+Keywords: ci-cd,data-contracts,data-mesh,dbt,semver
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: semver>=3.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dbt_contracts
+
+> A lightweight **data contract control plane** for multi-repository dbt ecosystems.
+
+dbt model contracts validate what a model publishes internally, but in a multi-repository data-product ecosystem, producers also need to know whether proposed interface changes violate downstream consumer expectations without cloning or rebuilding downstream repositories in CI.
+
+`dbt_contracts` provides:
+
+- **Canonical Data Contracts**: Infrastructure-independent contract models with column schemas, types, nullability, and provenance.
+- **dbt Artifact Ingestion**: Automatic extraction of public data models from dbt `manifest.json`.
+- **Central Contract Registry**: SQLite-based (and extensible) registry storing immutable contract history and consumer declarations.
+- **Explicit Consumer Expectations**: Downstream teams declare version ranges and required columns in simple YAML.
+- **SemVer Compatibility Engine**: Deterministic classification of changes as `PATCH`, `MINOR`, `MAJOR`, or `UNKNOWN`.
+- **Consumer Impact Analysis**: Identify which specific consumers and models will break when an interface changes.
+- **CI PR Gates**: Producer CI runs `dbt-contracts check` with standardized exit codes (`0` = valid, `1` = breaking gate failure, `2` = error).
+- **Organization-Scale Discovery**: Scan Azure DevOps organizations to discover dbt projects and consumer contracts without cloning.
+
+---
+
+## Architecture
+
+```text
+dbt artifacts / repository metadata
+              |
+              v
+      Discovery & Ingestion
+              |
+              v
+    Canonical Contract Model
+              |
+      +-------+---------+
+      |                 |
+      v                 v
+Contract Registry   Compatibility Engine
+      |                 |
+      +--------+--------+
+               |
+               v
+        Consumer Impact
+               |
+               v
+            CI Gate
+```
+
+---
+
+## Installation
+
+```bash
+pip install dbt-data-contracts
+```
+
+For development:
+
+```bash
+git clone https://github.com/your-org/dbt_contracts.git
+cd dbt_contracts
+python -m venv .venv
+source .venv/bin/activate  # Or .venv\Scripts\Activate.ps1 on Windows
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart & CLI Usage
+
+### 1. Ingest contracts from a dbt manifest
+
+Inspect public contracts discovered in a dbt manifest:
+
+```bash
+dbt-contracts ingest --manifest target/manifest.json
+```
+
+### 2. Publish a contract version to the registry
+
+Publish contracts for public dbt models (e.g. `1.0.0`):
+
+```bash
+dbt-contracts publish \
+  --manifest target/manifest.json \
+  --version 1.0.0 \
+  --registry .contracts.db
+```
+
+### 3. Register a downstream consumer expectation
+
+Downstream consumers define `data-contract-consumers.yml`:
+
+```yaml
+consumer: finance
+
+dependencies:
+  - product: orders
+    model: fct_orders
+    version: "^1.0.0"
+    expectations:
+      columns:
+        order_id:
+          data_type: bigint
+          required: true
+        amount:
+          data_type: numeric
+          required: true
+```
+
+Register the expectation in the central registry:
+
+```bash
+dbt-contracts consumer register \
+  --file data-contract-consumers.yml \
+  --registry .contracts.db
+```
+
+### 4. Check proposed changes in Producer CI
+
+In producer pull request pipelines, test proposed contracts against published contracts and registered consumers:
+
+```bash
+dbt-contracts check \
+  --manifest target/manifest.json \
+  --proposed-version 1.1.0 \
+  --registry .contracts.db
+```
+
+If a breaking change is detected (e.g., removing `amount` while `finance` requires it), the command outputs a detailed impact report and exits with code `1`:
+
+```text
+BREAKING CHANGE DETECTED: orders.fct_orders
+
+Proposed: 1.1.0 (Current: 1.0.0)
+Severity: MAJOR
+
+Breaking changes:
+  - Column 'amount' was removed
+
+Affected consumers:
+  - finance (expects 'amount: numeric', pinned to ^1.0.0)
+
+SemVer Validation:
+  FAIL: Breaking changes require a MAJOR version bump (expected >= 2.0.0).
+```
+
+If the proposed version is updated to `2.0.0`:
+
+```bash
+dbt-contracts check \
+  --manifest target/manifest.json \
+  --proposed-version 2.0.0 \
+  --registry .contracts.db
+```
+
+The check passes with exit code `0`, confirming that `1.0.0` remains intact for existing consumers while `2.0.0` introduces the new breaking contract.
+
+---
+
+## Development & Validation
+
+Run all checks:
+
+```bash
+pytest
+ruff check .
+ruff format --check .
+mypy src tests
+```
+
+Or run the dev check script:
+
+```bash
+./scripts/dev-check.sh
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.