entropy-tracker 1.0.3

A Code Aging & Decay Tracker - measures software entropy per module using git analysis, dependency drift, churn ratios, and knowledge decay signals.

Entropy - Code Aging & Decay Tracker

boto/compat.py scores 69. 490 modules depend on it. Every author who wrote it is gone. Its dependencies are years out of date. Nobody flagged this. Until now.

---

Software does not just accumulate bugs. It ages. The library it depends on evolved. The engineers who wrote it have left. Entropy makes that risk visible — as a number, per module, before production goes down.

---

Install

pip install entropy-tracker

Requirements: Python 3.10+, Git in your system PATH. No API keys. No telemetry. Runs securely in your environment. Source code never leaves your machine. Dependency versions are checked via read-only queries to the public PyPI API.

---

Quick Start

entropy init ./my-repo                 # register repo + first scan
entropy report --top 10                # worst modules by decay score
entropy inspect payments/gateway.py   # full breakdown + forecast
entropy diff --base main               # entropy delta for current branch

First results in under 60 seconds on most repositories.

---

Sample Output

---

What It Measures

Four signals combine into one composite score (0–100):

Signal	What it detects	Weight
Knowledge Decay	% of this file's authors who are still active in the repo	35%
Dependency Decay	How far behind this module's direct dependencies are	30%
Churn-to-Touch Ratio	Chaotic edits vs intentional refactors	20%
Age Without Refactor	Months since the last deliberate restructure	15%

How signals are computed: Knowledge decay checks author activity within a 36-month window. Churn is classified by total lines touched (>200 = churn) vs net line change (<10 with multi-file changes = refactor) - not by commit messages, which are unreliable. Dependency checks query PyPI for current release history and pip-audit for CVE counts.

Weights reflect recovery cost. Knowledge decay has the highest weight because lost institutional knowledge is irreversible on any sprint timescale. You can update a dependency in an afternoon. You cannot rebuild three years of context in a sprint.

Scores above 85 are Critical. Above 70 are High. All weights are configurable via entropy.toml.

---

Does It Actually Work?

We ran Entropy across Django, boto, and requests. Files scoring above 70 showed significantly more bug-fix and hotfix commits in their history than files below 50. The correlation is not causal - high-entropy files attract bugs and are touched repeatedly to fix them, which compounds the score over time. This is the pattern Entropy is designed to surface before it becomes an incident.

The tool processed Django's 2,903 modules across 2,782 commits in 34 seconds.

---

CI Integration

entropy diff --base main
# Shows entropy delta for every file changed in the current branch

# .github/workflows/entropy.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0        # full history required — do not use fetch-depth: 1
- run: pip install entropy-tracker && entropy diff --base main

---

Performance

Repository	Modules	Scan Time
click	62	~11s
Django	2,903	~34s
boto (full history)	938	~45s

Subsequent scans are faster — PyPI responses are cached locally for 24 hours.

---

Why Not SonarQube / Dependabot / CodeScene?

Tool	Prevents bugs	Surfaces knowledge loss risk
SonarQube	✅	❌
Dependabot	✅	❌
CodeScene	Partially	Partially (no dep drift, no CI diff, enterprise pricing)
Entropy	—	✅

Entropy's focus is not code quality. It is the risk that comes from a module nobody fully understands anymore — which no other tool in this list measures.

---

---

Roadmap

• entropy simulate --author-leaves [e-mail]
• JavaScript / TypeScript support
• GitHub Actions marketplace integration
• Validation dataset: entropy score vs production incident correlation

---

Built by Hari om Singh · PyPI · MIT License