Metadata-Version: 2.4
Name: b9x-faultline
Version: 0.1.0
Summary: Static, warehouse-free impact analysis for dbt pull requests. See what breaks before you merge.
Author-email: B9X <admin@b9x.ai>
Maintainer-email: B9X <admin@b9x.ai>
License: MIT
Project-URL: Homepage, https://github.com/b9x-ai/faultline
Project-URL: Repository, https://github.com/b9x-ai/faultline
Project-URL: Issues, https://github.com/b9x-ai/faultline/issues
Keywords: dbt,data-engineering,lineage,ci,impact-analysis,data-quality
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlglot>=25.0.0
Dynamic: license-file

# Faultline

**See what your dbt change breaks — before you merge it.**

Faultline is a static, warehouse-free impact analysis tool for dbt pull requests. It reads
two `manifest.json` snapshots (the base branch and your PR branch) and tells you exactly
which downstream models and columns your change will break — posted right on the pull request.

It never connects to your warehouse. **Your data never leaves CI.**

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

---

## Why

A one-line change to a dbt model — renaming or removing a column — can silently break
downstream models and the dashboards built on them. You usually find out *after* it ships.
Faultline catches it at review time, inside the pull request, before it merges.

## Install

```bash
pip install b9x-faultline
```

## Use it locally

```bash
# 1. Build the manifest from your main branch
git checkout main && dbt compile && cp target/manifest.json base.json

# 2. Build the manifest from your PR branch
git checkout my-branch && dbt compile && cp target/manifest.json head.json

# 3. See the impact
faultline --base base.json --head head.json
```

Add `--fail-on-break` to make it exit with an error when a breaking change is found
(useful in CI). Use `--dialect snowflake` (or `bigquery`, `postgres`, …) to match your
warehouse's SQL.

## Use it in GitHub Actions

Copy `.github/workflows/faultline.yml` into your dbt repo. On every pull request it compiles
both branches, runs Faultline, and posts the impact report as a comment — failing the check
if a breaking change is found.

## What it reports

| Signal | Meaning |
|---|---|
| 🔴 **breaking** | A downstream model references a column you removed. |
| 🟡 **warning** | A downstream model does `SELECT *` from the changed model, so its output schema shifts. |
| ⚪ **info** | Depends on the change but doesn't touch the affected columns. |

## How it works

Faultline parses your dbt SQL with [sqlglot](https://github.com/tobymao/sqlglot) — it reads
the code, it never runs it. That's why it needs no warehouse, no credentials, and no access
to your data. It builds the downstream dependency graph from your manifest, then checks each
affected model's columns against what changed.

## Honest limits

This is static analysis. On very complex, multi-hop SQL it will sometimes mark a downstream
model as **info — review this** rather than a definitive **breaking**. It degrades safely —
it surfaces the affected model for review and never goes silent — but deep column-level
tracing across many layers is an area we're actively improving.

## License

MIT — see [LICENSE](LICENSE).

## Contact

Built by B9X · admin@b9x.ai · https://github.com/b9x-ai/faultline
