Metadata-Version: 2.4
Name: arch-auditor
Version: 0.1.0
Summary: Evidence-backed repository architecture analysis with deterministic detectors and a Gemini refactoring assistant.
Author: Aniketh Sai
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/ANIKETHSAI9813/auditor
Project-URL: Repository, https://github.com/ANIKETHSAI9813/auditor
Keywords: architecture,analyzer,dependency,refactoring,streamlit
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: google-genai>=1.0
Requires-Dist: streamlit>=1.30
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Dynamic: license-file

# arch-auditor

Evidence-backed repository architecture analysis. Deterministic static
analysis first (AST-level facts, import graphs, cycle detection, coupling,
blast radius), with Gemini as an optional explain-and-plan assistant. Ships a
Streamlit web app and a CLI from the same engine.

- Python 3.10+
- Detectors: circular dependencies, high coupling, large modules, layer
  violations; plus a blast-radius impact report per module.
- Ruleset-driven layer validation (`config/architecture.yaml`).
- Architecture model, findings, severity, impact: `arch_auditor/models/`.
- Detector engine: `arch_auditor/analyzer/`.
- Gemini integration (overview, per-finding insights, refactoring plans):
  `arch_auditor/ai/`.
- Streamlit single-page app: `app.py` (7 sections per the UI spec).

## Install

```bash
pip install -e .
```

or, once published, `pip install arch-auditor`.

## CLI

```bash
# Analyze a repository
arch-auditor analyze path/to/repo

# Analyze the bundled demo repository
arch-auditor demo

# Ask Gemini for a refactoring plan for one finding (needs GEMINI_API_KEY)
arch-auditor plan CIRCULAR_DEPENDENCY_1 path/to/repo

# Version
arch-auditor --version
```

The CLI returns exit code 1 when findings exist, 0 when the repository is
clean, and 2 for usage errors. The Gemini key is read from the environment
only and is never logged.

## Web app

```bash
streamlit run app.py
```

Open the generated localhost URL. Enter a repository path (default: the
bundled `demo_repo`) and press ANALYZE.

For Streamlit Community Cloud: connect the repo and set the main script path
to `arch-auditor/app.py`. Dependencies come from `arch-auditor/requirements.txt`.

## Reference architecture ruleset

Layer validation is opt-in: drop `config/architecture.yaml` (see
`arch_auditor/config/architecture.yaml`) into the repository being analyzed.
Without a ruleset, layer validation is skipped and the remaining detectors run
on structure alone.

## Gemini key

Optional. Set `GEMINI_API_KEY` in the environment (CLI) or paste a key into
the app's sidebar (session only).

## Demo repository

`demo_repo/` is an intentionally problematic repository that exercises every
detector:

- cycle `orders -> payments -> users -> orders`
- `payment_service.py`: > 30 functions (LARGE_MODULE), fan-in 5 + fan-out 1
  (HIGH_COUPLING, HIGH impact)
- `database.py -> api.py` inverts the layer rules (LAYER_VIOLATION)

## Development

```bash
pip install -e ".[dev]"
ruff check .
pytest -q
python -m build
```

CI (`.github/workflows/ci.yml`) runs ruff, pytest, pip-audit (dependency
CVE scan), and builds + verifies the distribution on every push and PR.
CodeQL and weekly Dependabot updates keep the supply chain current.

## License

GPL-3.0-only. See [`LICENSE`](LICENSE) in the repository root and
`arch-auditor/LICENSE` (shipped inside the wheel).
