# Integrations

PyVisualizer is designed to live inside the workflows you already run. Every
command is pure AST analysis — no code is imported or executed — so it is safe
to run in CI, in pre-commit, and in air-gapped environments.

## Easiest path: `init`

Don't hand-write any of the YAML below unless you want to. `init` generates
**only** the automation you pick — nothing else — and never overwrites your
files without `--force`:

```bash
py-code-visualizer init --list                       # see the profiles; writes nothing
py-code-visualizer init --with review,context        # PR review comment + agent-context freshness
py-code-visualizer init --with readme,gates --ci github
py-code-visualizer init --with review --ci gitlab    # writes an includable pyvisualizer.gitlab-ci.yml
```

Profiles: `review` (PR review comment), `readme` (self-healing diagram),
`context` (ARCHITECTURE.json + AGENTS.md + a freshness gate), `gates` (cycle /
layer CI gate). Your choice is recorded as `features = [...]` in
`[tool.pyvisualizer]`. The sections below show what each profile writes, if you'd
rather wire it by hand.

## Configuration (`pyproject.toml`)

Declare defaults once so CI/pre-commit invocations are flag-free:

```toml
[tool.pyvisualizer]
exclude = ["tests", "migrations"]
max_nodes = 120
target = "README.md"
detail = "module"          # module | class | function

[tool.pyvisualizer.rules]
layers = ["api", "domain", "infra"]
forbid = ["domain -> api", "domain -> infra"]
```

## GitHub Actions

### PR review comment (Job 1)

Post a focused review — changed functions, blast radius, risk flags, and a
changed-neighborhood diagram — as a comment on every pull request:

```yaml
# .github/workflows/pyvisualizer-review.yml  (generated by `init --with review`)
name: Architecture review
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }          # full history so the base diff works
      - uses: actions/setup-python@v5
        with: { python-version: '3.x' }
      - run: pip install py-code-visualizer
      - run: py-code-visualizer review . --base "origin/${{ github.base_ref }}" -o review.md
      - uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            await github.rest.issues.createComment({
              ...context.repo, issue_number: context.issue.number,
              body: fs.readFileSync('review.md', 'utf8')
            });
```

Add `--fail-above N` to the `review` command to also fail the check when the
blast radius exceeds `N` callers (off by default — `review` is a report).

### Verified context freshness (Job 2)

Keep the committed `ARCHITECTURE.json` / `AGENTS.md` that your AI agents read in
sync with the code — a PR that drifts fails the check:

```yaml
# generated by `init --with context`
- run: pip install py-code-visualizer
- run: py-code-visualizer export . --check    # non-zero if the exported ground truth is stale
```

### Self-healing README

```yaml
- uses: haider1998/PyVisualizer@v2
  with:
    mode: readme
    target: README.md
```

### Architecture gate (fail on cycles / layer violations)

```yaml
- uses: haider1998/PyVisualizer@v2
  with:
    mode: gate
    fail-on-cycles: 'true'
```

The bundled workflows in `.github/workflows/` show the full PR-diff-comment
pattern (base vs. head graph diff, posted as a PR comment, failing on new
circular dependencies).

## Pre-commit

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/haider1998/PyVisualizer
    rev: v2.0.0
    hooks:
      - id: pyvisualizer-readme      # keep README diagram in sync
      - id: pyvisualizer-gate        # block cycles / layer violations locally
```

Both hooks are fast because they only parse the AST — nothing is imported.

## GitLab CI

```yaml
# .gitlab-ci.yml
architecture:
  image: python:3.11
  stage: test
  script:
    - pip install py-code-visualizer
    # Fail the pipeline on circular dependencies:
    - py-code-visualizer check . --fail-on-cycles --exclude tests
    # Keep the README diagram current (commit via a downstream job / bot):
    - py-code-visualizer readme . --target README.md
  artifacts:
    paths:
      - README.md
```

For merge-request diffs, generate `base.json` on the target branch and
`head.json` on the source branch, then `py-code-visualizer diff base.json
head.json` and post the Markdown to the MR via the GitLab API.

## Feeding the graph to AI tools

```bash
py-code-visualizer export --for-ai .   # ARCHITECTURE.json + ARCHITECTURE.md + AGENTS.md section
```

`export` also injects a marker-delimited section into `AGENTS.md` (the file
Copilot, Cursor, and Claude Code read automatically) telling the agent to consult
the verified graph and to run `context` for task-scoped facts. Pass
`--no-agents-md` to skip it.

For a specific task, hand the agent a small, verified slice instead of the whole
repo:

```bash
py-code-visualizer context . --focus your_pkg.core.save    # one function + its neighborhood
py-code-visualizer context . --from-git origin/main        # everything the PR changed
```

The pack contains verified signatures, call edges (with confidence + `file:line`),
and any cycles touching the focus — **97% fewer tokens** than the whole
source on a large project, with no guessed edges. Point your agent at the graph,
not the repo — deterministic ground truth, not a guess.