# import-cruiser

[![PyPI version](https://img.shields.io/pypi/v/import-cruiser.svg)](https://pypi.org/project/import-cruiser/)
[![Python versions](https://img.shields.io/pypi/pyversions/import-cruiser.svg)](https://pypi.org/project/import-cruiser/)
[![Workflow](https://github.com/kevin91nl/import-cruiser/actions/workflows/workflow.yml/badge.svg?branch=main)](https://github.com/kevin91nl/import-cruiser/actions/workflows/workflow.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#license)

Analyze, validate, and visualize Python import dependencies.

`import-cruiser` helps you quickly answer:
- Where are tight couplings?
- Are there circular imports?
- Are architecture rules respected?

## Why teams use it

- Fast graph export to `html`, `svg`, and `dot`
- Rule-based validation for CI (`validate --strict`)
- Readable interactive HTML output for architecture reviews
- Works out of the box on regular Python codebases

## See it in action: project self-graph

Dependency graph of `src/import_cruiser`, generated by the tool itself:

![import-cruiser self graph](./artifacts/self-graph/import-cruiser-self-graph.svg)

## Install

```bash
pip install import-cruiser
```

## 60-second quick start

From your repo root:

```bash
# 1) Generate an interactive dependency graph
import-cruiser export . --format html --output deps.html

# 2) Generate an embeddable SVG
import-cruiser export . --format svg --output deps.svg

# 3) Detect cycles and get a JSON report
import-cruiser analyze . --output report.json
```

For larger repos, filter noise:

```bash
import-cruiser export . \
  --format html \
  --include-path '^src/' \
  --exclude-common-noise-paths \
  --output deps-src.html
```

## Commands

```text
import-cruiser analyze  <path>   # analyze imports, output json/dot/svg/html
import-cruiser export   <path>   # export graph dot/svg/html
import-cruiser validate <path>   # enforce dependency rules
```

## Most useful options

- `--format {json,dot,svg,html}`
- `--include`, `--exclude`
- `--include-path`, `--exclude-path`
- `--exclude-common-noise-paths`
- `--cluster-depth`, `--cluster-mode`
- `--include-db-connectors`, `--include-http-hosts`
- `--show-loc` to show LOC per node/cluster and total LOC badge in HTML

## Validate architecture in CI

Minimal `import-cruiser.json` example:

```json
{
  "rules": [
    {
      "name": "no-data-to-ui",
      "severity": "error",
      "from": { "path": "\\.data" },
      "to": { "path": "\\.ui" },
      "allow": false
    }
  ]
}
```

Run in CI:

```bash
import-cruiser validate . --config import-cruiser.json --strict --output-format github
```

## Development

```bash
poetry install
poetry run pytest
```

## License

MIT
