dbt-extra 0.1.0__tar.gz

dbt_extra-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.venv-package-smoke/
+
+# Local dbt artifacts
+**/target/
+**/dbt_packages/
+**/logs/
+**/.user.yml
+*.duckdb
+*.duckdb.wal
+.pytest_cache/
+**/extra/review/
+
+# Temporary Excel lock files
+~$*.xlsx

dbt_extra-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 — Initial release
+
+First version of **dbt-extra**.
+
+- Distribution `dbt-extra`, Python package `dbt_extra`, and CLI `extra`.
+- Native dbt SQL, property YAML, macros and snapshots remain authoritative.
+- Offline validation, full-model and selected-column inspection, logical plans,
+  bounded local macro previews, and explicit analysis coverage reasons.
+- Folder-grouped XLSX and CSV reviews, read-only JSON catalogs, and
+  baseline-checked edits back to authored files with YAML comment preservation.
+- Conservative source SQL optimization and missing-metadata enrichment;
+  `--preview` / `--dry-run` writes nothing.
+- Optional `extra_project.yaml` and `EXTRA_PROJECT_DIR`; review exports default
+  to `extra/review/` with format version 1 and no branded format identifiers.
+- Metadata enrichment and review import update existing dbt YAML entries only;
+  missing entries are reported and skipped, never created automatically.
+- Documentation, executable Jaffle Shop examples and native dbt integration
+  fixture, tests, package smoke checks and cross-platform CI.
+- MIT licensing and third-party Apache 2.0 seed attribution.
+- Adopted the maintainer-supplied Modular joint / Lagoon SVG icon, preserving
+  its paths and palette across light/dark variants, plus a monochrome asset.
+- PyPI trusted publishing after CI on `v*` tags or manual dispatch, with
+  release-tag/package-version verification for tag runs.

dbt_extra-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to dbt-extra
+
+extra is an offline dbt transformation companion. Changes should keep authored SQL,
+business metadata and review outputs inspectable, with dbt responsible for
+database execution. Read the [concepts](docs/concepts.md) and
+[architecture](docs/development/architecture.md) first.
+
+## Set up and test
+
+Use Python 3.11+ and [uv](https://docs.astral.sh/uv/), then run from the repository root:
+
+```sh
+uv sync --locked
+uv run pytest
+uv run extra --project-dir examples/jaffle_shop validate
+uv run extra --project-dir examples/jaffle_shop export --preview
+uv run extra --project-dir examples/jaffle_shop optimize --preview
+uv build
+```
+
+The suite includes documentation/link checks and DuckDB result-equivalence tests.
+See [testing](docs/development/testing.md) for the executable dbt checks and
+clean-install package smoke tests. Do not run write-mode optimization against
+bundled teaching inputs just to test a change; copy them to a temporary project.
+
+## Propose a change
+
+- Useful first contributions include a small redacted dialect/macro reproduction,
+  a regression test, or a clearer walkthrough. Check existing issues first; if no
+  suitable issue exists, describe your proposed scope before a substantial change.
+- For significant behavior/schema changes, open an issue describing the use case
+  before building an incompatible API. Small documentation fixes can go straight
+  to a pull request.
+- Keep changes focused. Include a minimal reproduction and regression test for
+  bugs; include expected inputs/outputs for new features.
+- Preserve output-column order, declared metadata, validation-before-write
+  behavior, unchanged-file bytes and managed-path protections.
+- Prefer explicit errors to guessed schema information. No warehouse access may
+   be introduced into offline analysis commands without an explicit design change.
+- Update relevant docs and [CHANGELOG](CHANGELOG.md) for user-visible changes.
+  Follow [compatibility](docs/compatibility.md) for schema/API changes.
+- Write block-style YAML and plain GitHub-readable Markdown. Link reference docs
+  rather than duplicating their full content in the README.
+- Do not commit credentials, local databases, dbt logs/targets or generated demo
+  dbt output. The example workbook and seed data are intentional fixtures.
+
+In your pull request, state what changed, why, commands tested, limitations and
+any migration required. If AI helped, review its output and verify business
+assumptions yourself; do not submit untested generated logic as verified behavior.
+
+## Report bugs and security issues
+
+For ordinary bugs, include dbt-extra/Python/OS versions, the exact command, a minimal
+redacted project and expected versus actual behavior. Never post private
+catalogs, credentials or production data. Use the [security policy](SECURITY.md)
+for potential vulnerabilities rather than disclosing exploit details publicly.
+For source checkouts, also include `git rev-parse HEAD`; unreleased code can share
+the published package's version string. The GitHub issue forms collect these details.
+
+## License
+
+Contributions to dbt-extra code and documentation are under the [MIT license](LICENSE).
+Preserve third-party notices and the separate Jaffle Shop seed attribution.

dbt_extra-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 billybillysss
+
+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_extra-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: dbt-extra
+Version: 0.1.0
+Summary: Offline dbt transformation review, inspection, editing, and optimization
+Project-URL: Repository, https://github.com/billybillysss/dbt-extra
+Project-URL: Documentation, https://github.com/billybillysss/dbt-extra/blob/HEAD/docs/index.md
+Project-URL: Issues, https://github.com/billybillysss/dbt-extra/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: ruamel-yaml<0.20,>=0.18
+Requires-Dist: sqlglot<30.25,>=30.8
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dbt-extra-mark-dark.svg">
+    <img src="docs/assets/dbt-extra-mark.svg" alt="dbt-extra — Modular joint icon" width="128" height="128">
+  </picture>
+</p>
+
+<h1 align="center">dbt-extra — dbt transformation review and inspection</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0D9488" alt="License: MIT"></a>
+  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.11+"></a>
+  <a href="https://github.com/billybillysss/dbt-extra/actions/workflows/ci.yml"><img src="https://github.com/billybillysss/dbt-extra/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="docs/index.md"><img src="https://img.shields.io/badge/docs-read-0D9488" alt="Documentation"></a>
+</p>
+
+<p align="center">
+  <a href="docs/getting-started.md">Get started</a> · <a href="docs/index.md">Documentation</a> · <a href="docs/guides/ai-assisted-workflow.md">AI-assisted workflow</a> · <a href="examples/jaffle_shop/README.md">Native dbt demo</a> · <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+**Trace a dbt column back to its SQL. Review transformations in Excel.
+Preview edits to the original files—all offline.**
+
+Where does `revenue` come from? Which filters change it? Can a reviewer update
+its description without hunting through YAML? dbt-extra helps answer those questions
+using the dbt project you already have. No warehouse credentials, dbt compilation,
+or second model language required.
+
+## See where a column comes from
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). From a terminal:
+
+```bash
+git clone https://github.com/billybillysss/dbt-extra.git
+cd dbt-extra
+uv sync --locked
+uv run --locked extra --project-dir examples/jaffle_shop inspect customer_revenue --columns revenue --compile false
+```
+
+The bundled example follows `customer_revenue → orders → demo_raw_orders`.
+The explanation retains the **completed-order filter**, **decimal cast** and
+**per-customer grouping**, even though you selected only `revenue`.
+
+<details>
+<summary>See the SQL output (CLI comments omitted)</summary>
+
+```sql
+SELECT
+  "extra_selected_output"."revenue" AS "revenue"
+FROM (
+  WITH order_totals AS (
+    SELECT
+      SUM(CAST("extra_input_2".amount AS DECIMAL(12, 2))) AS revenue
+    FROM {{ ref('demo_raw_orders') }} AS "extra_input_2"
+    WHERE
+      "extra_input_2".status = 'completed'
+    GROUP BY
+      "extra_input_2".customer_id
+  )
+  SELECT
+    order_totals.revenue + 0 AS revenue
+  FROM order_totals AS order_totals
+) AS "extra_selected_output";
+```
+
+This is a definition explanation, not executed SQL or proof about stored data.
+The seed remains an explicit boundary. Authored files are unchanged.
+
+</details>
+
+Stop at an upstream model with `--from orders`, or use `--view plan` for a logical
+tree. [Try the walkthrough →](docs/getting-started.md)
+
+> **Private preview · 0.1.0:** install from this checkout with repository access.
+> The executable is `extra`; Python imports use `dbt_extra`.
+
+## Pick your workflow
+
+| You want to… | Use dbt-extra to… |
+| --- | --- |
+| Understand one output column | Follow supported upstream SQL while retaining joins, filters, grouping and row multiplicity. |
+| Review SQL and metadata together | Export a folder-grouped XLSX workbook or CSV, edit supported cells, and preview diffs back to dbt files. |
+| Review an AI-proposed change | Export read-only JSON with SQL, dependencies, column lineage and explicit coverage reasons for an external assistant. |
+| Clean up authored SQL | Preview conservative rewrites that preserve dbt calls; unsafe or opaque cases are skipped with reasons. |
+| Fill missing documentation | Infer available types and unambiguous passthrough descriptions without overwriting authored metadata. |
+
+### Review in Excel, apply through a diff
+
+```bash
+uv run --locked extra --project-dir examples/jaffle_shop export --format xlsx --select customer_revenue
+# Edit supported cells in examples/jaffle_shop/extra/review/review.xlsx, then close Excel.
+uv run --locked extra --project-dir examples/jaffle_shop import examples/jaffle_shop/extra/review/review.xlsx --preview
+```
+
+The workbook groups `TABLE → STEP / OUTPUT → COLUMN` rows. Supported edits patch
+the original SQL/YAML; stale exports are rejected, YAML comments are preserved,
+and unchanged files keep their bytes. Preview writes nothing. Follow the
+[round-trip walkthrough](docs/guides/catalog-round-trip.md) before applying edits.
+
+### Preview SQL cleanup and metadata proposals
+
+```bash
+uv run --locked extra --project-dir examples/jaffle_shop optimize --select customer_revenue --preview
+uv run --locked extra --project-dir examples/jaffle_shop enrich --select customer_revenue --preview
+```
+
+For more visible before/after SQL rewrites, try the
+[14 focused optimizer demos](examples/jaffle_shop/models/gld/optimization/README.md).
+Logical cleanup is **not** a measured warehouse speedup.
+
+## Use your existing dbt project
+
+Point `--project-dir` at your project and supply its actual SQL dialect:
+
+```bash
+uv run --locked extra --project-dir path/to/your/dbt_project --dialect snowflake inspect your_model --columns your_column
+```
+
+dbt SQL and property YAML remain the source of truth. No initialization is
+required. Optional `extra_project.yaml` stores tool settings only:
+
+```yaml
+version: 2
+analysis:
+  dialect: duckdb
+export:
+  format: xlsx
+  output_dir: extra/review
+  select:
+    - 'path:models/gld/**'
+optimization:
+  format: pretty
+  preserve_macros: true
+```
+
+Explicit CLI values replace configured values, including lists. `--preview`
+(`--dry-run`) writes no files. Without it, writing commands apply their
+[documented writes](docs/reference/cli.md). See the
+[existing-project guide](docs/guides/existing-dbt-project.md) for artifact and dialect setup.
+
+## Python API
+
+```python
+from dbt_extra import Project
+from dbt_extra.analysis import catalog
+from dbt_extra.optimization import optimize
+
+project = Project("examples/jaffle_shop")
+document = catalog(project, project.select(["customer_revenue"]))
+changes, skipped = optimize(project, select=["customer_revenue"])
+print(changes.diffs())
+# changes.apply()  # Explicitly accept the proposed source edits.
+```
+
+The CLI is the preferred entry point; Python integrations should pin and test
+versions. See [architecture](docs/development/architecture.md) for module boundaries.
+
+## Safety and maturity
+
+extra is pre-1.0 and conservative by design:
+
+- **Unknowns stay explicit.** Coverage depends on dialect, schemas and Jinja.
+  Bounded static local macros can be previewed; runtime/adapter-dependent macros
+  remain opaque. Generated SQL never replaces an authored macro call.
+- **dbt still owns execution.** dbt-extra is not a dbt engine, metrics service or
+  warehouse optimizer. Inspection explains definitions, not equivalence to
+  persisted or incremental relations. Run your own dbt parsing, tests and builds.
+- **Writes still need review.** Package/artifact-only resources and inherited
+  version properties are read-only. Full opaque-template edits are structure-checked,
+  not dbt-compiled. Baseline checks and rollback attempts are not crash-safe
+  multi-file transactions or file locks.
+
+See [compatibility](docs/compatibility.md) and the
+[production adoption checklist](docs/guides/production-workflow.md).
+
+## Help shape dbt-extra
+
+Try one model from your own project. If analysis stops, share a **minimal redacted
+reproduction** and the coverage reason in an
+[issue](https://github.com/billybillysss/dbt-extra/issues). Dialect edge cases,
+documentation improvements and regression tests are especially useful.
+Read [Contributing](CONTRIBUTING.md) to get started; report vulnerabilities through
+the [security policy](SECURITY.md), not a public bug report.
+
+[Get started](docs/getting-started.md) · [CLI](docs/reference/cli.md) ·
+[Configuration](docs/reference/configuration.md) · [Review contract](docs/reference/catalogs.md) ·
+[Inspection and optimization](docs/guides/inspection-and-optimization.md) ·
+[Native example](examples/jaffle_shop/README.md) · [Contributing](CONTRIBUTING.md)

dbt_extra-0.1.0/README.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dbt-extra-mark-dark.svg">
+    <img src="docs/assets/dbt-extra-mark.svg" alt="dbt-extra — Modular joint icon" width="128" height="128">
+  </picture>
+</p>
+
+<h1 align="center">dbt-extra — dbt transformation review and inspection</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0D9488" alt="License: MIT"></a>
+  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.11+"></a>
+  <a href="https://github.com/billybillysss/dbt-extra/actions/workflows/ci.yml"><img src="https://github.com/billybillysss/dbt-extra/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="docs/index.md"><img src="https://img.shields.io/badge/docs-read-0D9488" alt="Documentation"></a>
+</p>
+
+<p align="center">
+  <a href="docs/getting-started.md">Get started</a> · <a href="docs/index.md">Documentation</a> · <a href="docs/guides/ai-assisted-workflow.md">AI-assisted workflow</a> · <a href="examples/jaffle_shop/README.md">Native dbt demo</a> · <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+**Trace a dbt column back to its SQL. Review transformations in Excel.
+Preview edits to the original files—all offline.**
+
+Where does `revenue` come from? Which filters change it? Can a reviewer update
+its description without hunting through YAML? dbt-extra helps answer those questions
+using the dbt project you already have. No warehouse credentials, dbt compilation,
+or second model language required.
+
+## See where a column comes from
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). From a terminal:
+
+```bash
+git clone https://github.com/billybillysss/dbt-extra.git
+cd dbt-extra
+uv sync --locked
+uv run --locked extra --project-dir examples/jaffle_shop inspect customer_revenue --columns revenue --compile false
+```
+
+The bundled example follows `customer_revenue → orders → demo_raw_orders`.
+The explanation retains the **completed-order filter**, **decimal cast** and
+**per-customer grouping**, even though you selected only `revenue`.
+
+<details>
+<summary>See the SQL output (CLI comments omitted)</summary>
+
+```sql
+SELECT
+  "extra_selected_output"."revenue" AS "revenue"
+FROM (
+  WITH order_totals AS (
+    SELECT
+      SUM(CAST("extra_input_2".amount AS DECIMAL(12, 2))) AS revenue
+    FROM {{ ref('demo_raw_orders') }} AS "extra_input_2"
+    WHERE
+      "extra_input_2".status = 'completed'
+    GROUP BY
+      "extra_input_2".customer_id
+  )
+  SELECT
+    order_totals.revenue + 0 AS revenue
+  FROM order_totals AS order_totals
+) AS "extra_selected_output";
+```
+
+This is a definition explanation, not executed SQL or proof about stored data.
+The seed remains an explicit boundary. Authored files are unchanged.
+
+</details>
+
+Stop at an upstream model with `--from orders`, or use `--view plan` for a logical
+tree. [Try the walkthrough →](docs/getting-started.md)
+
+> **Private preview · 0.1.0:** install from this checkout with repository access.
+> The executable is `extra`; Python imports use `dbt_extra`.
+
+## Pick your workflow
+
+| You want to… | Use dbt-extra to… |
+| --- | --- |
+| Understand one output column | Follow supported upstream SQL while retaining joins, filters, grouping and row multiplicity. |
+| Review SQL and metadata together | Export a folder-grouped XLSX workbook or CSV, edit supported cells, and preview diffs back to dbt files. |
+| Review an AI-proposed change | Export read-only JSON with SQL, dependencies, column lineage and explicit coverage reasons for an external assistant. |
+| Clean up authored SQL | Preview conservative rewrites that preserve dbt calls; unsafe or opaque cases are skipped with reasons. |
+| Fill missing documentation | Infer available types and unambiguous passthrough descriptions without overwriting authored metadata. |
+
+### Review in Excel, apply through a diff
+
+```bash
+uv run --locked extra --project-dir examples/jaffle_shop export --format xlsx --select customer_revenue
+# Edit supported cells in examples/jaffle_shop/extra/review/review.xlsx, then close Excel.
+uv run --locked extra --project-dir examples/jaffle_shop import examples/jaffle_shop/extra/review/review.xlsx --preview
+```
+
+The workbook groups `TABLE → STEP / OUTPUT → COLUMN` rows. Supported edits patch
+the original SQL/YAML; stale exports are rejected, YAML comments are preserved,
+and unchanged files keep their bytes. Preview writes nothing. Follow the
+[round-trip walkthrough](docs/guides/catalog-round-trip.md) before applying edits.
+
+### Preview SQL cleanup and metadata proposals
+
+```bash
+uv run --locked extra --project-dir examples/jaffle_shop optimize --select customer_revenue --preview
+uv run --locked extra --project-dir examples/jaffle_shop enrich --select customer_revenue --preview
+```
+
+For more visible before/after SQL rewrites, try the
+[14 focused optimizer demos](examples/jaffle_shop/models/gld/optimization/README.md).
+Logical cleanup is **not** a measured warehouse speedup.
+
+## Use your existing dbt project
+
+Point `--project-dir` at your project and supply its actual SQL dialect:
+
+```bash
+uv run --locked extra --project-dir path/to/your/dbt_project --dialect snowflake inspect your_model --columns your_column
+```
+
+dbt SQL and property YAML remain the source of truth. No initialization is
+required. Optional `extra_project.yaml` stores tool settings only:
+
+```yaml
+version: 2
+analysis:
+  dialect: duckdb
+export:
+  format: xlsx
+  output_dir: extra/review
+  select:
+    - 'path:models/gld/**'
+optimization:
+  format: pretty
+  preserve_macros: true
+```
+
+Explicit CLI values replace configured values, including lists. `--preview`
+(`--dry-run`) writes no files. Without it, writing commands apply their
+[documented writes](docs/reference/cli.md). See the
+[existing-project guide](docs/guides/existing-dbt-project.md) for artifact and dialect setup.
+
+## Python API
+
+```python
+from dbt_extra import Project
+from dbt_extra.analysis import catalog
+from dbt_extra.optimization import optimize
+
+project = Project("examples/jaffle_shop")
+document = catalog(project, project.select(["customer_revenue"]))
+changes, skipped = optimize(project, select=["customer_revenue"])
+print(changes.diffs())
+# changes.apply()  # Explicitly accept the proposed source edits.
+```
+
+The CLI is the preferred entry point; Python integrations should pin and test
+versions. See [architecture](docs/development/architecture.md) for module boundaries.
+
+## Safety and maturity
+
+extra is pre-1.0 and conservative by design:
+
+- **Unknowns stay explicit.** Coverage depends on dialect, schemas and Jinja.
+  Bounded static local macros can be previewed; runtime/adapter-dependent macros
+  remain opaque. Generated SQL never replaces an authored macro call.
+- **dbt still owns execution.** dbt-extra is not a dbt engine, metrics service or
+  warehouse optimizer. Inspection explains definitions, not equivalence to
+  persisted or incremental relations. Run your own dbt parsing, tests and builds.
+- **Writes still need review.** Package/artifact-only resources and inherited
+  version properties are read-only. Full opaque-template edits are structure-checked,
+  not dbt-compiled. Baseline checks and rollback attempts are not crash-safe
+  multi-file transactions or file locks.
+
+See [compatibility](docs/compatibility.md) and the
+[production adoption checklist](docs/guides/production-workflow.md).
+
+## Help shape dbt-extra
+
+Try one model from your own project. If analysis stops, share a **minimal redacted
+reproduction** and the coverage reason in an
+[issue](https://github.com/billybillysss/dbt-extra/issues). Dialect edge cases,
+documentation improvements and regression tests are especially useful.
+Read [Contributing](CONTRIBUTING.md) to get started; report vulnerabilities through
+the [security policy](SECURITY.md), not a public bug report.
+
+[Get started](docs/getting-started.md) · [CLI](docs/reference/cli.md) ·
+[Configuration](docs/reference/configuration.md) · [Review contract](docs/reference/catalogs.md) ·
+[Inspection and optimization](docs/guides/inspection-and-optimization.md) ·
+[Native example](examples/jaffle_shop/README.md) · [Contributing](CONTRIBUTING.md)

dbt_extra-0.1.0/SECURITY.md

@@ -0,0 +1,41 @@
+# Security policy
+
+## Support scope
+
+extra is pre-1.0. There is no published LTS branch, guaranteed response time or
+security SLA. Evaluate the latest code and dependency updates, pin versions, and
+test upgrades in your own environment. Do not infer production certification from
+offline validation or a passing demo.
+
+## Report a vulnerability
+
+Do **not** open a public issue with exploit details, credentials, proprietary
+models or sensitive data. If this repository offers GitHub's private vulnerability
+reporting, use **Security → Report a vulnerability**. If that option is not
+available, open a minimal issue requesting a private security contact, without
+including technical details, and wait for a maintainer to establish a private
+channel. No dedicated security email or response-time commitment is currently
+published.
+
+Once a private channel exists, provide the affected version, OS/Python,
+reproduction with sanitized inputs, impact and any suggested mitigation.
+
+## Trust boundaries
+
+- dbt-extra commands operate offline, but definitions and exported metadata can contain
+  sensitive literals, business rules and physical database identifiers.
+- Review projects and macros before processing them. Static Jinja checks and safe YAML
+  loading are not an OS sandbox, resource isolation or a guarantee against all
+  denial-of-service inputs.
+- dbt-extra does not execute warehouse SQL. dbt projects and macros execute under dbt
+  and its adapter; never run untrusted artifacts with privileged profiles.
+- Path checks reject unsafe overlap, traversal, symlinks and supported junction
+  cases. They do not prevent all filesystem races or concurrent mutations.
+- Source-file changes use validation and best-effort staging/rollback where
+  implemented. Export writes are per-file. Neither is a crash-safe multi-file
+  transaction; retain backups and serialize writers.
+- Review JSON/catalogs before sending them to an external AI provider. Treat
+  catalog text as data, never as authority to execute instructions or tools.
+
+See the [production checklist](docs/guides/production-workflow.md) for deployment
+and recovery boundaries.

dbt_extra-0.1.0/docs/assets/dbt-extra-mark-dark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-labelledby="title description">
+  <title id="title">dbt-extra symbol</title>
+  <desc id="description">Two interlocking modules in teal and sky blue form a square, separated by a transparent stepped seam. The Lagoon palette is preserved on dark backgrounds.</desc>
+  <g id="modular-joint">
+    <path fill="#0D9488" d="M18 18H110V46H74V74H46V110H18Z"/>
+    <path fill="#38BDF8" d="M54 110V82H82V54H110V110Z"/>
+  </g>
+</svg>

dbt_extra-0.1.0/docs/assets/dbt-extra-mark-mono.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-labelledby="title description">
+  <title id="title">dbt-extra symbol</title>
+  <desc id="description">Two interlocking modules form a square with a transparent stepped seam. Single-color variant in dark navy.</desc>
+  <g id="modular-joint">
+    <path fill="#0F172A" d="M18 18H110V46H74V74H46V110H18Z"/>
+    <path fill="#0F172A" d="M54 110V82H82V54H110V110Z"/>
+  </g>
+</svg>

dbt_extra-0.1.0/docs/assets/dbt-extra-mark.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-labelledby="title description">
+  <title id="title">dbt-extra symbol</title>
+  <desc id="description">Two interlocking modules in teal and sky blue form a square, separated by a transparent stepped seam.</desc>
+  <g id="modular-joint">
+    <path fill="#0D9488" d="M18 18H110V46H74V74H46V110H18Z"/>
+    <path fill="#38BDF8" d="M54 110V82H82V54H110V110Z"/>
+  </g>
+</svg>

dbt_extra-0.1.0/docs/compatibility.md

@@ -0,0 +1,55 @@
+# Compatibility and versioning
+
+## Current boundaries
+
+| Surface | Current contract |
+| --- | --- |
+| Package | `dbt-extra`, version `0.1.0`; private preview, pre-1.0. Executable `extra`, Python namespace `dbt_extra`. Pin and test upgrades. |
+| Python | Metadata requires 3.11+. CI targets 3.11 and 3.13 on Linux, plus 3.13 on Windows. Other Python/platform combinations are not thereby certified. |
+| SQLGlot | Runtime dependency is constrained to `>=30.8,<30.25`, tested at 30.8.0 and 30.24.0. Dialect availability does not establish warehouse execution support. |
+| Tool settings | Optional `extra_project.yaml`, `version: 2`; no transformation authoring schema. |
+| Review JSON | `format_version: 1`, `source_of_truth: dbt`. Read-only analysis; check coverage and the envelope. |
+| dbt | Native authored SQL/properties/macros/snapshots. No compile/runtime emulation. Execution compatibility depends on your dbt and adapter versions. The native demo uses DuckDB. |
+| Python internals | Not a separately guaranteed stable public API. Prefer the CLI or explicitly version-tested integrations. |
+
+CI declares test targets; a new matrix entry is not proof it has passed until
+that workflow runs successfully. The development environment uses DuckDB for
+local execution checks; it does not run a remote warehouse integration.
+No macOS CI or warehouse performance benchmark is currently provided.
+
+The supported range stops before 30.25: 30.25.0 failed existing window-alias
+`QUALIFY` regressions, and fresh-install checks with 30.29.0 exposed further API
+and SQL-rendering differences. The exclusion is not a general certification of
+every other SQLGlot version; CI also tests a freshly resolved installed wheel.
+
+## Initial version
+
+`dbt-extra` starts at `0.1.0` as a private preview.
+Install from an authorized source checkout and record its Git commit when
+reporting results. The repository stays private until
+verification and separate maintainer approval to make it public.
+
+Public visibility, package publication and branding are separate release gates;
+see the [release checklist](development/releasing.md).
+
+## Upgrade policy
+
+Before upgrading, keep a Git baseline and export reviews into an isolated
+directory. Compare validation, SQL, properties, review JSON, mutation diffs and
+dbt results. Check [CHANGELOG](../CHANGELOG.md) for documented changes.
+
+Use the responsibility-based packages described in [architecture](development/architecture.md)
+for version-tested Python integrations. Review files must follow the
+[review contract](reference/catalogs.md), including their export baseline.
+
+Use `optimization.preserve_macros: true`; native rewrites never expand macros.
+`--preview` is the unified no-write option; `--dry-run` remains an alias.
+
+## Maintainer policy for future changes
+
+Record user-visible changes under Unreleased. Document CLI/config/schema changes,
+add regression tests, and provide migration instructions for incompatible changes.
+If the JSON contract becomes incompatible, update its format version rather than
+silently reinterpreting existing fields. Additive fields should not require
+consumers to reject an otherwise supported envelope. dbt-extra does not currently
+provide a general JSON Schema validator or migration service.