Metadata-Version: 2.4
Name: entropy-tracker
Version: 1.0.0
Summary: A Code Aging & Decay Tracker - measures software entropy per module using git analysis, dependency drift, churn ratios, and knowledge decay signals.
Author-email: Hari om Singh <singh.omhari715@gmail.com>
License: MIT
Keywords: entropy,code-aging,decay,technical-debt,git-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydriller>=2.6
Requires-Dist: gitpython>=3.1
Requires-Dist: typer[all]>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: fastapi>=0.104
Requires-Dist: uvicorn[standard]>=0.24
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: asyncpg>=0.29
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: celery[redis]>=5.3
Requires-Dist: redis>=5.0
Requires-Dist: httpx>=0.25
Requires-Dist: aiohttp>=3.8
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: alembic>=1.13
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# Entropy

The engineer who wrote `payments/gateway.py` left 18 months ago. Nobody else understands it. Entropy tells you that before production goes down.

![Entropy Report Output](./assets/demo.png)

Software does not just accumulate bugs. It **ages**. Code written three years ago, never touched, slowly becomes dangerous — not because it broke, but because the world around it changed. The library it depends on evolved. The external API it calls shifted its contract. The engineers who wrote it have left. 

This is **software entropy**. Entropy is a continuously-running analysis engine that combines git history, dependency drift, and code churn into a single decay score per module, and projects it forward in time.

---

## Quick Start

Get your first risk score in 3 commands:

```bash
# Install the CLI
pip install entropy-tracker

# Register a repository and run the first scan
entropy init ./my-repo

# See your most decayed, highest-risk modules
entropy report --top 10
```

---

## What Entropy Measures

Entropy combines four distinct signals into one module-level composite score (0–100):

| Signal | What it measures | Why it matters |
|--------|-----------------|----------------|
| **Knowledge Decay** | % of authors who touched this module that are still active | A module where 5 of 6 authors have gone inactive is a knowledge silo. |
| **Dependency Decay** | How far behind this module's direct dependencies are | A 12-month-old dep in a fast-moving ecosystem is riskier than a stable one. |
| **Churn-to-Touch** | Ratio of chaotic edits to intentional refactors | High churn with no refactoring = technical debt accumulating invisibly. |
| **Age Without Refactor** | Months since the last structural refactor | Old code that is never deliberately revisited drifts from team understanding. |

### The Entropy Output

Modules are scored from 0 to 100:
- **0–50 (Healthy):** Active authors, up-to-date dependencies, regular refactoring.
- **50–70 (Medium):** Aging code. Starting to drift.
- **70–85 (High):** Risky to touch. Single points of failure emerging.
- **85–100 (Critical):** A fire hazard. Do not ship features through this without remediation. 

You can inspect exactly why a file is failing:
```bash
entropy inspect payments/gateway.py
```

### Advanced Forecasting & Alerts

Because Entropy stores scores over time, it computes the **decay velocity** of each module and projects forward.

```bash
entropy forecast payments/gateway.py
# Output:
# 30 days → 90 (CRITICAL)
# 90 days → 97 (CRITICAL)
# Estimated unmaintainable: ~4 months
```

---

## Architecture 

Entropy runs entirely locally with zero external telemetry. The architecture includes:
- **Git Analyzer:** PyDriller + GitPython extract author decay and churn ratios.
- **Dep Analyzer:** PyPI API concurrent requests + pip-audit identify drift.
- **TimescaleDB:** Time-series storage for continuous scoring and forecasting.
- **FastAPI / Celery:** Optional background scheduler to continuously monitor repositories overnight.

## Roadmap & v2 Features

We are actively building features to embed Entropy permanently in engineering workflows:
- **PR-level Diffing:** `entropy diff --base main` to block PRs that increase complexity on undocumented modules.
- **Simulations:** "What happens to the codebase if Engineer X leaves?"
- **Ecosystem Expansion:** Full JavaScript / TypeScript support.
