dblect 0.1.0__tar.gz

dblect-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Single version to conserve Actions minutes; widen the matrix back to the
+        # full supported range (3.11-3.13) when budget allows.
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff check)
+        run: uv run ruff check
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check
+
+      - name: Type-check (pyright strict)
+        run: uv run pyright
+
+      # -n auto parallelises across the runner's cores; loadscope keeps each module on
+      # one worker so the module-scoped dbt-compile fixtures still run once apiece.
+      # Coverage instrumentation adds ~45% to the test step (measured) and nothing gates
+      # on it, so it runs only on the main push that publishes the artifact, keeping the
+      # PR feedback path on the uninstrumented run of the same tests.
+      - name: Tests (pytest)
+        if: github.event_name != 'push'
+        run: uv run pytest -n auto --dist loadscope
+
+      - name: Tests (pytest with coverage)
+        if: github.event_name == 'push'
+        run: uv run pytest -n auto --dist loadscope --cov --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage artifact
+        if: github.event_name == 'push' && matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error

dblect-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+
+# Publishes to PyPI when a v* tag is pushed. The wheel and sdist are built on a
+# clean runner from the tagged commit, and upload uses PyPI Trusted Publishing
+# (OIDC): no API token is stored anywhere. The `pypi` environment matches the
+# trusted-publisher registration on PyPI and is the place to add a manual
+# approval gate if one is ever wanted.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dblect
+    permissions:
+      id-token: write # required for OIDC; this is what authorizes the upload
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Guard tag against the packaged version
+        # The tag drives the release, but the wheel's version comes from
+        # _version.py via hatchling. If they disagree the upload would ship a
+        # surprise, so require the built wheel to carry the tag's version and
+        # fail loudly before publishing a mismatch.
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          if [ ! -f "dist/dblect-${tag}-py3-none-any.whl" ]; then
+            echo "tag ${GITHUB_REF_NAME} has no matching wheel; built:" >&2
+            ls dist >&2
+            exit 1
+          fi
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

dblect-0.1.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+# /MANIFEST is the setuptools sdist artifact at repo root.
+# Anchored to root so our src/dblect/manifest/ package is not matched
+# case-insensitively on macOS/Windows filesystems.
+/MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+HANDOFF.md
+
+# Claude Code local worktrees
+.claude/worktrees/

dblect-0.1.0/CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-11
+
+The first published release: the base-world static analyzer, packaged for
+`pip install dblect`. It reads a compiled dbt manifest, propagates column-level
+facts through the DAG, and reports structural and declaration-level findings the
+user can navigate to and act on. No execution and no LLM are required. The
+runtime half (property-based execution, replay-determinism) and the
+flag/var-world analysis are deferred to later releases.
+
+### Added
+
+**Manifest and SQL ingestion**
+
+- Typed dbt manifest ingestion: `Manifest`, `Node`, and a `Dag` with topology,
+  parsed from `manifest.json`.
+- Analysis over each model's compiled SQL (not the raw Jinja), parsed once per
+  run and shared across detectors via a sqlglot wrapper.
+- `catalog.json` ingestion for seed and source columns, so undocumented DAG
+  leaves resolve.
+- Source-Jinja front end that discovers `var` and `env_var` references, and a
+  typed view of the manifest's macro registry.
+
+**Column-level lineage substrate**
+
+- A K-relations / semiring propagator carrying where-provenance through the DAG,
+  with CTE and UNION intermediates materialized in the lineage graph.
+- The `lineage.facts` substrate: one property propagator over a shared fact
+  representation, with nullability discoverers backed by the manifest.
+- Conditional facts that carry their guarding predicate, a predicate-implication
+  engine, and a predicate-flow property that accumulates each relation's row
+  filter, so conditional uniqueness, candidate keys, and `NOT NULL` activate
+  across relations and at intra-model scopes.
+- Nested-field (STRUCT) lineage with explicit `UNNEST` grain.
+
+**Uniqueness analysis**
+
+- Uniqueness facts from dbt declarations and from structural proof, an
+  ordering-key detector and a join-fan-out detector over substrate keys, and
+  propagation of uniqueness through SQL operations and across model
+  dependencies.
+- Candidate keys derived through surrogate-hash columns; seeds and snapshots
+  spanned as test targets.
+
+**Domain-type contracts (the declaration DSL)**
+
+- The authoring core: `DomainType`, `ModelContract`, `Field`, and the bridge
+  that lowers a contract to substrate facts.
+- A contract and proxy layer: an expression AST, column proxies, the
+  `@contract` decorator, and fact constructors.
+- Companion-binding column properties (the currency story), may/must refinement
+  for widened magnitudes, and domain-type transfer through joins
+  (functional-dependency-through-join, outer-join taint, join-key and fan-out
+  signals).
+- A config discoverer that grounds an incremental model's `unique_key`, and
+  fact-level flag-world plumbing.
+- Wider scalar field types in the classifier: `float` / `Float` as a magnitude,
+  `Timestamp` / `datetime` as inert siblings of `Date`, and a bare integer
+  (`int` / `Integer` / `BigInt`) accepted as opaque (inert) under the lenient
+  default, the ambiguous case a future strict mode rejects (#73).
+
+**Structural hazard detectors**
+
+- Structural detectors over every model: outer-join `WHERE` inversion,
+  non-determinism, the NULL-group-after-outer-join family (`GROUP BY`, join
+  key, `NOT IN`), and snapshot reads missing a temporal filter.
+- Source-line provenance on every finding, and SQLFluff-compatible `-- noqa`
+  suppression. A bare `-- noqa` silences every dblect finding on its line; a
+  `-- noqa: DBLECT_<KIND>` directive silences one detector, and codes without the
+  `DBLECT_` prefix are left for `dbt lint` so one comment can address both tools.
+  This replaces the earlier bespoke `-- noqa-fixture:` syntax: dblect no longer owns
+  the suppression grammar, so it coexists with dbt Fusion's `dbt lint` rather than
+  competing with it. Every suppression is still logged in the report's `suppressed:`
+  section.
+
+**Cross-world analysis**
+
+- One analysis door (`dblect.analysis.analyze`) over both detector families,
+  returning every finding under one sealed type so a consumer cannot silently
+  drop a family.
+- Incremental-worlds checking: compile a model's full-refresh and steady-state
+  forms data-free, run both detector families over each, and difference the
+  findings so a hazard living only in the unexercised branch surfaces.
+- Coverage reporting that separates resolution (lineage the propagator could
+  follow) from grounding (columns a fact actually checks).
+
+**CLI and reporting**
+
+- The `dblect` CLI: `check` runs both detector families over a project, `init`
+  scaffolds the declaration tree and writes model stubs, `version` prints the
+  installed version.
+- Text and JSON reporters under one versioned schema, with a non-zero exit on
+  unsuppressed findings and a `--no-fail` override. Status messages go to
+  stderr so stdout is a clean report.
+- A validated-adapter gate, with `--dialect` as the operator's opt-in
+  acknowledgment that detector behavior is best-effort off the validated set.
+- A library of demo scenarios: developer-introduced bugs that `dblect check`
+  catches.
+
+**Execution harness**
+
+- A DuckDB execution harness that runs dbt models via subprocess with fixture
+  overrides, the substrate the runtime layers will build on.
+
+### Changed
+
+- `aggregation_not_well_typed` findings now name what the coherence guard
+  reasoned about: the aggregate and the column it reduced, the per-row companion
+  that is not held constant, and the grouping that fails to hold it, instead of
+  a generic message (#109).
+- Aggregate behavior is now a first-class combine/select/count classification
+  (`dblect.sql.aggregates`), the single source of truth for both arming the
+  coherence guard and the not-well-typed finding. Keying on the sqlglot node type
+  covers every dialect at once; `min`/`max` are classified as selecting aggregates
+  and widen their result tag to top on a varying companion under the lenient
+  default (#115).
+
+### Fixed
+
+- `count` (and `count_if`, `approx_count_distinct`) over a typed magnitude no
+  longer raises a spurious `aggregation_not_well_typed` finding. Conversely,
+  `stddev`, `variance`, `kurtosis`, `skewness`, `median`, `mode`, and the
+  quantile/percentile family now correctly flag a mixed-currency reduction (#115).
+
+[Unreleased]: https://github.com/dvryaboy/dblect/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dvryaboy/dblect/releases/tag/v0.1.0

dblect-0.1.0/CLAUDE.md

@@ -0,0 +1,46 @@
+# Code Style
+We avoid stringy typing like the plague.
+We use rigorous types.
+
+We reach for an existing helper before writing a parallel one, and generalize it when a second caller needs a variant. A comment or commit message that reaches for "mirroring", "duplicate of", or "acceptable for now" is a signal to stop and reuse the original instead.
+
+## Testing
+We test rigorously. 
+Whenever applicable, we design quality PBT tests, or otherwise leverage provers and exhaustive testing.
+We do not write tests for tests' sakes. We avoid test theater. 
+We prefer to test at the boundaries instead of implementation specifics; tests should survive implementation
+changes that do not change contracts.
+Excessive use of mocking is a smell. Loads of boilerplate is a smell.
+Pin contracts, not coincidences. If fragile cooperation is observed (two functions work correctly together only because of implementation details, not contract guarantees), fix the contracts in code rather than pinning the accidental behavior in a test.
+
+We work test-first: the failing test (or the property / lattice-law spec) comes before the implementation, so it pins the intended contract rather than rationalizing whatever the code happens to do. When the contract is amenable, we design the property-based test and its generators first, before the code, so the generator is not shaped to fit the implementation.
+
+A whole suite passing on its first run is a smell rather than a win: it usually means the tests are weak or were written after the code. When it happens, we prove the tests bite by injecting deliberate contract violations and confirming a test fails for each.
+
+We enumerate the input space rather than sampling it: a condition over a closed type earns a test per value, and the common ones (`COUNT(*)` among the duplicate-sensitive aggregates) belong in that space rather than being deferred as edge cases.
+
+## Soundness
+We discharge each predicate or guard to an exact decision procedure before coding it, with a counterexample that marks its edge and a test that pins it. A plausible structural proxy standing in for a precise semantic condition is where the subtle bugs live.
+
+A soundness check that branches on a closed type decides every case explicitly, rather than handling one (a `CROSS` join) and letting the rest fall through to the wrong answer.
+
+When new code consumes an existing fact or invariant, we re-establish that fact's soundness across its full input space, even when we did not write it. A new consumer can raise the stakes on a latent over-claim and turn it into a wrong answer.
+
+## Comments
+We avoid comment bloat. We write comments that explain the why of things, or help understand particularly
+complex bits of code and call attention to footguns.
+
+Specific things to keep out of comments, docstrings, and prose:
+- Phase or tier numbering ("Tier 0", "phase 1", etc.). The numbering is arbitrary and reorderable; refer to work streams by name (e.g., "static analyser", "replay-determinism check", "runtime PBT loop").
+- Narrative counts of fixture or repo contents ("5 models + 3 seeds + 20 tests"). They go stale silently; if a number matters, assert it.
+- References to ephemeral planning files such as `HANDOFF.md`. Those are session-to-session notes and should not be cited from code, tests, or docs.
+
+## Prose Style
+All narrative documents and comments should avoid em-dashes and "not x. not y. z" phrasing.
+We do not bash older or alternative approaches: we win by being clear and positive, and complimenting them / acknowledging good ideas and influences when appropriate. We are generous with compliments and praise. We put our work in the context of the broader field. 
+
+# Development
+We run Python and its tooling through `uv` (`uv run python`, `uv run pytest`, `uv run ruff`, `uv run pyright`); a bare `python` is not on PATH. Quick probes go through `uv run python -c "..."` rather than a throwaway file.
+
+Before pushing we run the full gate, which CI runs as separate steps: `uv run ruff check`, `uv run ruff format --check`, `uv run pyright`, `uv run pytest`.
+