Metadata-Version: 2.4
Name: archsight
Version: 0.1.1
Summary: Static dependency-graph analysis for Python, JavaScript/TypeScript, and C++
Project-URL: Homepage, https://github.com/ROHITH-KUMAR-L/archsight
Project-URL: Repository, https://github.com/ROHITH-KUMAR-L/archsight
Project-URL: Issues, https://github.com/ROHITH-KUMAR-L/archsight/issues
Author: archsight contributors
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: networkx>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: temporal
Requires-Dist: gitpython>=3.1; extra == 'temporal'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1; extra == 'test'
Requires-Dist: pytest>=7.4; extra == 'test'
Requires-Dist: ruff>=0.1; extra == 'test'
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter-cpp>=0.20; extra == 'tree-sitter'
Requires-Dist: tree-sitter-javascript>=0.20; extra == 'tree-sitter'
Requires-Dist: tree-sitter-python>=0.20; extra == 'tree-sitter'
Requires-Dist: tree-sitter-typescript>=0.20; extra == 'tree-sitter'
Requires-Dist: tree-sitter>=0.20; extra == 'tree-sitter'
Description-Content-Type: text/markdown

# archsight — Dependency Graph Analysis Engine

> Detect cycles, find critical files, compute safe build order, and measure blast-radius impact using classical graph algorithms — no API keys, no network, no dashboard required.

![Language](https://img.shields.io/badge/Language-Python%203.11%2B-blue) ![CLI](https://img.shields.io/badge/CLI-Typer-4B8BBE) ![Graph](https://img.shields.io/badge/Graph-NetworkX-orange) ![Optional](https://img.shields.io/badge/Optional-GitPython%20%2F%20tree--sitter-9cf) ![License](https://img.shields.io/badge/License-MIT-brightgreen)

---

## Executive Summary

`archsight` is a pip-installable Python library and CLI that statically analyzes Python, JavaScript/TypeScript, and C++ codebases, builds a directed dependency graph, and runs graph algorithms against it to surface architectural risk.

It is a pure, deterministic analysis engine — not a web app, not a visualization tool, not AI-powered. It runs fully offline (aside from the optional local git-mining feature) and is built to drop into CI pipelines, pre-commit hooks, and agent sessions without a running server or a browser.

| | |
|---|---|
| **Cycle detection** | Find circular dependencies with full cycle paths |
| **Build ordering** | Compute a safe topological build order |
| **Critical files** | Identify articulation points — single points of failure |
| **Parallel waves** | Group files into build layers that can run concurrently |
| **Blast radius** | See what breaks if you change a given file |
| **Refactor plan** | Rank the minimum edges to cut to make the graph acyclic (MFAS) |
| **Temporal coupling** | Mine git history for hidden co-change relationships *(optional)* |

---

## Installation

```bash
pip install archsight

# with temporal (git history) analysis:
pip install "archsight[temporal]"
```

Requires **Python 3.11+**.

---

## Quick start

```bash
archsight scan ./my-project --fail-on-cycle
```

Human-readable output in your terminal, non-zero exit code if a cycle is found. Wire it into CI and you're done.

---

## CLI

```bash
# Scan a project
archsight scan ./my-project

# Scan only specific languages
archsight scan ./my-project --lang python,javascript

# Run a subset of algorithms
archsight scan ./my-project --only cycles,articulation

# Output formats
archsight scan ./my-project --format json -o report.json
archsight scan ./my-project --format markdown -o report.md

# CI mode: exit code 1 if cycles found
archsight scan ./my-project --fail-on-cycle

# Blast-radius impact analysis for a single file
archsight impact ./my-project --file utils.py

# Temporal coupling (requires the [temporal] extra)
archsight temporal ./my-project --max-commits 30 --min-cochange 2
```

<details>
<summary><strong>All flags</strong></summary>

| Flag | Description |
|---|---|
| `--lang` | Comma-separated list of languages to include |
| `--only` | Comma-separated list of algorithms to run |
| `--format` | `text` (default), `json`, or `markdown` |
| `-o, --output` | Write report to a file instead of stdout |
| `--fail-on-cycle` | Exit with code `1` if any cycle is detected |
| `--max-commits` | *(temporal)* Number of commits to mine |
| `--min-cochange` | *(temporal)* Minimum co-change count to report a coupling |

</details>

---

## Python API

```python
from archsight import analyze

result = analyze("/path/to/project")

result.cycles                 # list of Cycle objects
result.build_order            # topological order, or None if cycles exist
result.articulation_points    # list of ArticulationPoint objects
result.build_waves            # parallel build layers, or None if cyclic
result.mfas                   # edges to remove for acyclic refactoring
result.impact                 # ImpactResult for a changed file, if requested
```

Format the result however you need:

```python
from archsight.report import format_json, format_markdown, format_table

print(format_json(result))
print(format_markdown(result))
print(format_table(result))
```

---

## Architecture

```
parsers/   →  produces edge lists only (source, target, import type, line)
               never touches networkx or graph algorithms

graph/     →  pure graph algorithms
               never knows what language produced its edges

temporal/  →  optional git history mining (requires archsight[temporal])
```

This boundary is deliberate: adding a 4th language is a **parser-only** change — the graph algorithms don't change at all.

---

## Testing

```bash
pip install -e ".[test]"
pytest tests/ -v
```

---

## License

MIT