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.

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.

Installation

pip install archsight

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

Requires Python 3.11+.

Quick start

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

# 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

Python API

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:

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

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

License

MIT