Metadata-Version: 2.4
Name: impactgraph
Version: 0.7.1
Summary: Pre-merge safety net: what breaks if I merge this? Blast radius, risk, owners and a test plan on every PR - built on datagraph.
Author: Sumit Gupta
License: MIT
Project-URL: Homepage, https://github.com/sumit-gupta03/impactgraph
Project-URL: Engine, https://github.com/sumit-gupta03/datagraph
Project-URL: Issues, https://github.com/sumit-gupta03/impactgraph/issues
Keywords: impact-analysis,blast-radius,pull-request,ci,dependency-graph,dbt,lineage,change-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: datagraph-core>=0.8.2
Provides-Extra: sql
Requires-Dist: datagraph-core[sql]; extra == "sql"
Provides-Extra: yaml
Requires-Dist: datagraph-core[yaml]; extra == "yaml"
Provides-Extra: ai
Requires-Dist: datagraph-core[ai]; extra == "ai"
Provides-Extra: all
Requires-Dist: datagraph-core[all]; extra == "all"
Provides-Extra: dev
Requires-Dist: datagraph-core[sql,yaml]; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# impactgraph

**What breaks if I merge this?** — a pre-merge safety net for code *and* data.

`impactgraph` takes the git diff of a pull request, maps it onto a deterministic dependency graph
(Python/JS functions → Lambdas/APIs → tables → dbt models → columns → dashboards) and reports the
**blast radius, risk level, owners to notify and a test plan** — as a terminal report, JSON, a
Markdown PR comment, or an interactive HTML view — with an exit code you can gate CI on.

It is the pull-request product built on **[datagraph](https://github.com/sumit-gupta03/datagraph)**,
the engine that holds everything data-related: extractors (Python, dbt, SQL, warehouse metadata,
Airflow, Lambda, JS, OpenLineage, DataHub, plugins), lineage, relationships, profiling, the
knowledge base for AI assistants and the MCP server. impactgraph re-exports the whole engine, so one
install gives you both.

```
git diff  ──►  changed functions / models / files  ──►  graph walk  ──►  risk · owners · tests
```

## Install

```bash
pip install impactgraph            # core (pulls in datagraph)
pip install "impactgraph[sql]"     # + sqlglot for .sql files and column lineage
pip install "impactgraph[all]"     # + yaml, anthropic (AI explanation), mcp
```

## 30-second use

```bash
# uncommitted changes in the working tree, Python code + dbt
impactgraph check --repo . --dbt-manifest target/manifest.json

# a PR branch against main, Markdown for the PR comment, fail the job at HIGH or above
impactgraph check --repo . --base origin/main --format markdown --fail-on HIGH

# machine-readable, and keep the graph for later questions
impactgraph check --repo . --base origin/main --format json --save-graph impactgraph.json
impactgraph impact dbt:customer --graph impactgraph.json       # any datagraph command passes through
impactgraph lineage table:prod.analytics.dim_customer --graph impactgraph.json
impactgraph context dim_customer --graph impactgraph.json      # knowledge pack for an AI assistant
```

Typical output (text format):

```
changed files (1): src/etl/load_customers.py
Changed: func:src/etl/load_customers.py::load_customers   risk HIGH (score 20.0)
├── ▤ prod.analytics.customer (table) via writes_to
│   └── ◆ dim_customer (dbt_model) via depends_on
│       └── ◆ fact_booking (dbt_model) via depends_on
│           ├── 📊 revenue_report (dashboard) via exposes
│           └── 📊 customer_dashboard (dashboard) via exposes
Notify: finance (revenue_report) · growth (customer_dashboard)
Recommended tests:
  ✓ pytest -k load_customers
  ✓ dbt build --select dim_customer+ fact_booking+
  ✓ Manually validate 'revenue_report' after deploy
```

`check` options: `--base/--head`, `--code DIR` (code root if not the repo root), `--graph FILE` / `--save-graph FILE --update`,
every datagraph build input (`--dbt-manifest --dbt-catalog --sql --airflow --lambda --js --warehouse --openlineage --lineage-file --datahub`),
`--max-depth`, `--no-inferred` (artifact-backed edges only), `--format text|json|markdown`, `--html FILE`, `--fail-on LEVEL`, `-o FILE`.

## GitHub Action — a comment on every PR

```yaml
# .github/workflows/impact.yml
name: change impact
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
  impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - uses: sumit-gupta03/impactgraph@main
        with:
          repo-path: src
          dbt-manifest: target/manifest.json
          fail-on: CRITICAL        # LOW | MEDIUM | HIGH | CRITICAL | NONE
```

The action installs impactgraph, diffs the PR against its base, posts the Markdown report as a PR comment
(and to the job summary) and exposes `level` as an output.

## Python API

```python
from impactgraph import check, to_markdown

result = check(".", base="origin/main", inputs={"dbt_manifest": "target/manifest.json"})
print(result.level, result.score, result.changed_files)
print(result.analysis.recommended_tests, result.analysis.owners)
print(to_markdown(result))                     # the PR comment
assert not result.breaches("HIGH")
```

Everything from datagraph is re-exported (`from impactgraph import ImpactGraph, analyze_impact, DbtExtractor, ...`).

## How it works (and why it is trustworthy)

1. **Deterministic graph** — built from artifacts only (AST, manifests, SQL parse, metadata, git). No LLM builds nodes.
2. **Typed edges with an impact direction** — `contains`, `writes_to`, `exposes` flow forward; `calls`, `imports`, `depends_on` flow backward — so a change propagates the way reality does.
3. **Provenance** — every edge is `extracted`, `inferred` or `llm`; `--no-inferred` drops heuristics.
4. **Diff → function** — changed line ranges map to the exact functions/models touched, not whole files.
5. **Risk, owners, tests** — a weighted score over affected node types (dashboards and tables weigh more), owners collected from dbt/DataHub metadata, test suggestions per node type.
6. **AI only explains** — `impactgraph explain ...` (optional `[ai]`) narrates the result; it never changes it.

## Use it from AI coding assistants

Copy `skills/impactgraph/` to `.claude/skills/impactgraph/` (or `~/.claude/skills/`) and ask
*"is this change safe?"*, *"what breaks if I change load_customers?"*. For MCP, the knowledge base
(`wiki`, `context`) and data analysis (`relationships`, `profile`) use datagraph directly.

## impactgraph vs datagraph

| | impactgraph | datagraph |
|---|---|---|
| Audience | developers, reviewers, CI | data engineers, analysts, AI-assistant builders |
| Question | *will this PR break something?* | *where does this data come from, how is it related, what does it look like, give my assistant the context* |
| Ships | `check` / `pr` CLI, GitHub Action, skill; passes everything else through | the engine: extractors, lineage, relationships, profiling, wiki/context, MCP, plugins |
| Graph & node ids | identical — a graph built by one is readable by the other | |

## Security

impactgraph inherits datagraph's security model (deterministic core, LLM only explains, prompts wrap repo/warehouse text as
untrusted data, DSN passwords never stored or logged, profiling masks sensitive columns, quoted identifiers, escaped HTML).
The PR comment is plain Markdown built from node names in *your* repository; the GitHub Action needs only `pull-requests: write`
and the default `GITHUB_TOKEN`. See the [datagraph security notes](https://github.com/sumit-gupta03/datagraph#security).

## Development

```bash
git clone https://github.com/sumit-gupta03/impactgraph && cd impactgraph
pip install -e ".[dev]"     # pulls datagraph-core from PyPI (the engine; import name datagraph)
pytest
```

History: versions ≤ 0.5 of this repository contained the whole engine; it now lives in
[datagraph](https://github.com/sumit-gupta03/datagraph) and impactgraph (≥ 0.6) is the thin PR-focused layer.

## License

MIT
