dbt-arch-unit 0.1.1__tar.gz

dbt_arch_unit-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: 🐛 Bug report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for taking the time to file a bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Commands run, relevant `dbt_arch_unit.yaml` snippet, and any model SQL.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: dbt-arch-unit version
+      description: Output of `dbt-arch-unit version`.
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: Python / dbt version & OS
+      placeholder: "Python 3.13, dbt 1.8, macOS 15"
+    validations:
+      required: false

dbt_arch_unit-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Questions & discussions
+    url: https://github.com/dardanxh/dbt-arch-unit/discussions
+    about: Ask questions, share setups, and discuss ideas here.
+  - name: 📖 Documentation
+    url: https://github.com/dardanxh/dbt-arch-unit#readme
+    about: Read the README and rule catalog first.

dbt_arch_unit-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: ✨ Feature request
+description: Suggest an enhancement (not a new rule — use the rule proposal template for that)
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: The use case or pain point motivating the request.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What you'd like to see happen. Include CLI/config examples if relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

dbt_arch_unit-0.1.1/.github/ISSUE_TEMPLATE/new_rule.yml

@@ -0,0 +1,62 @@
+name: 📐 New rule proposal
+description: Propose a new architecture/convention rule for dbt projects
+labels: ["rule-proposal"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Rules are small functions that check a dbt project against a convention.
+        See CONTRIBUTING.md for how they're implemented.
+  - type: input
+    id: name
+    attributes:
+      label: Proposed rule name
+      placeholder: "e.g. max-macro-depth"
+    validations:
+      required: true
+  - type: textarea
+    id: enforces
+    attributes:
+      label: What does it enforce?
+      description: The convention/best practice and why it matters.
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Data source
+      description: Where the check gets its information.
+      options:
+        - manifest (manifest.json)
+        - file (raw .sql/.yml)
+        - both
+    validations:
+      required: true
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - dependencies
+        - naming
+        - testing
+        - documentation
+        - style
+        - materialization
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Configuration options
+      description: Any `config:` keys the rule should accept (name + default).
+      placeholder: "max: maximum allowed value (default: 5)"
+    validations:
+      required: false
+  - type: textarea
+    id: example
+    attributes:
+      label: Example that should fail
+      render: sql
+    validations:
+      required: false

dbt_arch_unit-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Related issue
+
+<!-- e.g. Closes #123 -->
+
+## Changes
+
+<!-- Bullet the key changes. If you added/changed a rule, name it. -->
+
+## Checklist
+
+- [ ] `uv run ruff check` and `uv run ruff format --check` pass
+- [ ] `uv run mypy src` passes
+- [ ] `uv run pytest` passes
+- [ ] Added/updated tests (with a fixture case if a new rule)
+- [ ] Updated `README.md` / `CHANGELOG.md` if behaviour or the rule catalog changed

dbt_arch_unit-0.1.1/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies", "ci"]
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies"]

dbt_arch_unit-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check
+
+      - name: Type check (mypy)
+        run: uv run mypy src
+
+      - name: Tests (pytest)
+        run: uv run pytest

dbt_arch_unit-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+# Automated versioning + releases via python-semantic-release.
+# On every push to main it inspects Conventional Commits since the last tag and,
+# if there is a releasable change (feat/fix/perf/BREAKING CHANGE), bumps the
+# version, updates CHANGELOG.md, commits, tags vX.Y.Z, and creates a GitHub
+# Release. PyPI publishing is gated on the PYPI_PUBLISH repo variable so it stays
+# inert until you register a PyPI Trusted Publisher and set PYPI_PUBLISH=true.
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push the release commit + tag, create the GitHub Release
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      tag: ${{ steps.release.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs: release
+    if: needs.release.outputs.released == 'true' && vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dbt_arch_unit-0.1.1/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# dbt-arch-unit generated artifacts
+*_report.html
+dbt_arch_unit_report.html
+
+# Keep uv.lock tracked (it is the tool lockfile) — do NOT ignore it.

dbt_arch_unit-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# Local dev hooks for contributors. Install with: uv run pre-commit install
+# (This is separate from `.pre-commit-hooks.yaml`, which exposes dbt-arch-unit
+#  as a hook for *downstream* dbt projects to consume.)
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

dbt_arch_unit-0.1.1/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: dbt-arch-unit
+  name: dbt architecture unit tests
+  description: Enforce dbt architecture rules declared in dbt_arch_unit.yaml
+  entry: dbt-arch-unit check
+  language: python
+  pass_filenames: false
+  always_run: true

dbt_arch_unit-0.1.1/CHANGELOG.md

@@ -0,0 +1,45 @@
+# CHANGELOG
+
+All notable changes to this project are documented here. This file is generated
+automatically by [python-semantic-release](https://python-semantic-release.readthedocs.io)
+from [Conventional Commits](https://www.conventionalcommits.org) — do not edit by hand.
+
+<!-- version list -->
+
+## v0.1.1 (2026-08-23)
+
+### Bug Fixes
+
+- Ship py.typed marker for PEP 561 type support
+  ([`6d9635d`](https://github.com/dardanxh/dbt-arch-unit/commit/6d9635dba8d9cb7885e33f54de1072b5bd5e3ae5))
+
+The package declares "Typing :: Typed" but shipped no py.typed marker, so downstream type checkers
+  ignored dbt-arch-unit's inline types. Add the marker so consumers pick up the annotations.
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+
+
+## v0.1.0 (2026-08-23)
+
+### Continuous Integration
+
+- Automate versioning and releases with python-semantic-release
+  ([`9900087`](https://github.com/dardanxh/dbt-arch-unit/commit/9900087e648e40850b7f48e41a5fc5c8296f8ad1))
+
+Version, git tag, GitHub Release and CHANGELOG are now derived from Conventional Commit messages.
+  The release workflow runs PSR on pushes to main; PyPI publishing is gated behind the PYPI_PUBLISH
+  repo variable.
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+
+### Features
+
+- Dbt-arch-unit — architectural unit testing for dbt
+  ([`9407556`](https://github.com/dardanxh/dbt-arch-unit/commit/9407556e51dad87e50c12add5f43e0a5e2c6582a))
+
+Enforce a team's dbt conventions (layering, naming, testing, docs, style, materialization) via a
+  declarative dbt_arch_unit.yaml. Ships 38 rules, a Typer+Rich CLI
+  (check/report/list-rules/explain/init), a self-contained HTML report, and a pre-commit hook.
+  Includes CI, release automation, and full OSS governance files.
+
+Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

dbt_arch_unit-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,59 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**dardanxhymshiti@gmail.com**. All complaints will be reviewed and investigated
+promptly and fairly. All community leaders are obligated to respect the privacy
+and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

dbt_arch_unit-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing to dbt-arch-unit
+
+Thanks for your interest in improving **dbt-arch-unit**! This project turns a
+team's dbt conventions into enforceable, testable rules. Contributions — new
+rules, bug fixes, docs — are very welcome.
+
+## Development setup
+
+You need [uv](https://docs.astral.sh/uv/) and Python 3.13+.
+
+```bash
+git clone https://github.com/dardanxh/dbt-arch-unit
+cd dbt-arch-unit
+uv sync --extra dev          # install the package + dev tools
+uv run dbt-arch-unit --help  # sanity check
+```
+
+## The checks CI runs (run them before opening a PR)
+
+```bash
+uv run ruff check            # lint
+uv run ruff format --check   # formatting
+uv run mypy src              # static types (strict)
+uv run pytest                # tests
+```
+
+Optionally install the local git hooks so these run automatically:
+
+```bash
+uv run pre-commit install
+```
+
+## How the project is organised
+
+```
+src/dbt_arch_unit/
+  models/manifest.py   # typed view of dbt's manifest.json
+  parsers/             # manifest loader + raw-SQL fact extraction
+  config.py            # the dbt_arch_unit.yaml contract (pydantic)
+  context.py           # ProjectContext: layers, selectors, cached SQL, test indexes
+  rules/               # one module per category, one function per rule
+  runner.py reporting.py html_report.py cli.py scaffold.py
+tests/                 # per-category tests + a demo project fixture
+```
+
+## Adding a new rule
+
+Rules are small, self-contained functions registered by name. To add one:
+
+1. **Write the function** in the right category module under `src/dbt_arch_unit/rules/`
+   (`dependencies`, `naming`, `testing`, `documentation`, `style`, `materialization`).
+   Use the `@register(...)` decorator and the `(ctx, rule)` signature:
+
+   ```python
+   @register(
+       "no-select-star",
+       "style",
+       "Models must not use `select *` in their final projection.",
+       source="file",  # "manifest" | "file" | "both"
+       config_keys={"allow_in_ctes": "permit `select *` inside CTEs (default: true)"},
+   )
+   def no_select_star(ctx: ProjectContext, rule: RuleConfig) -> Iterable[Violation]:
+       for model in ctx.models_for(rule):  # scoping is handled for you
+           if ctx.sql(model).has_select_star(allow_in_ctes=rule.config.get("allow_in_ctes", True)):
+               yield ctx.violation(rule, model, "uses `select *`")
+   ```
+
+   Let `ctx.models_for(rule)` do the include/exclude/layer/tag scoping — never
+   re-implement it. Read manifest facts from `ctx`, and raw-SQL facts from
+   `ctx.sql(model)`.
+
+2. **Add a fixture case** if needed in `tests/fixtures/demo_project/` (the demo
+   project is deliberately "bad" so rules have something to catch).
+
+3. **Add a test** in the matching `tests/test_<category>.py` asserting exactly
+   which nodes the rule flags.
+
+4. **Document it** — it shows up automatically in `dbt-arch-unit list-rules` and
+   `explain <rule>` from the `@register` metadata. Add it to `CHANGELOG.md`.
+
+## Commit & PR conventions
+
+- Keep PRs focused; one rule or fix per PR where possible.
+- Ensure `ruff`, `mypy`, and `pytest` all pass.
+- Update `README.md` when behaviour or the rule catalog changes. **Do not** edit
+  `CHANGELOG.md` — it is generated automatically (see below).
+
+### Commit messages drive releases
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org)
+and [python-semantic-release](https://python-semantic-release.readthedocs.io).
+The commit type on `main` determines the next version and changelog entry — so
+**your commit message matters**:
+
+| Commit type                          | Release effect            |
+| ------------------------------------ | ------------------------- |
+| `fix: …`                             | patch (0.1.0 → 0.1.1)     |
+| `feat: …`                            | minor (0.1.0 → 0.2.0)     |
+| `feat!: …` or a `BREAKING CHANGE:` footer | major (0.1.0 → 1.0.0) |
+| `docs:` `chore:` `ci:` `refactor:` `test:` | no release          |
+
+On merge to `main`, the release workflow bumps the version in `pyproject.toml`
+and `src/dbt_arch_unit/__init__.py`, updates `CHANGELOG.md`, tags `vX.Y.Z`, and
+publishes a GitHub Release automatically. You can preview what would happen with:
+
+```bash
+uvx python-semantic-release version --print   # prints the next version, no changes
+```
+
+## Reporting bugs / proposing rules
+
+Open an issue using the templates — there's a dedicated **"New rule proposal"**
+template for suggesting architecture rules.
+
+By contributing you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

dbt_arch_unit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dardan Xhymshiti
+
+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.