entropy-tracker 1.0.0__tar.gz

entropy_tracker-1.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+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.

entropy_tracker-1.0.0/README.md

@@ -0,0 +1,81 @@
+# 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.

entropy_tracker-1.0.0/entropy/__init__.py

@@ -0,0 +1,9 @@
+"""
+ENTROPY — A Code Aging & Decay Tracker
+
+Computes decay scores per codebase module using git analysis,
+dependency drift, churn ratios, and knowledge decay signals.
+"""
+
+__version__ = "1.0.0"
+__app_name__ = "entropy"

entropy_tracker-1.0.0/entropy/analyzers/__init__.py

@@ -0,0 +1 @@
+"""Entropy analyzers — git history, dependency drift, and AST import graph."""

entropy_tracker-1.0.0/entropy/analyzers/ast_analyzer.py

@@ -0,0 +1,179 @@
+"""
+AST Analyzer — builds the import graph and computes blast radius.
+
+Uses Python's built-in ``ast`` module to parse every .py file in the repo,
+extract import statements, and build a directed graph of module dependencies.
+From this graph we compute:
+- Blast radius: how many modules transitively depend on a given module
+- Import graph adjacency list (for visualization/API)
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import warnings
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ImportGraphData:
+    """Complete import graph for a repository."""
+
+    # module_path → list of modules it imports (within-repo only)
+    imports: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list))
+    # module_path → list of modules that import it (reverse edges)
+    imported_by: dict[str, list[str]] = field(default_factory=lambda: defaultdict(list))
+    # module_path → transitive blast radius count
+    blast_radius: dict[str, int] = field(default_factory=dict)
+    # all known module paths
+    all_modules: set[str] = field(default_factory=set)
+
+
+class ASTAnalyzer:
+    """Build the import graph and compute blast radius for a Python repo."""
+
+    def __init__(self, repo_path: str | Path):
+        self.repo_path = Path(repo_path)
+        self._module_paths: dict[str, str] = {}  # dotted.name → relative/file/path
+
+    def analyze(self) -> ImportGraphData:
+        """
+        1. Discover all .py files and build a dotted-name registry
+        2. Parse each file's imports
+        3. Resolve imports to local modules
+        4. Build reverse graph and compute blast radius
+        """
+        logger.info("ASTAnalyzer: scanning %s …", self.repo_path)
+        graph = ImportGraphData()
+
+        # Step 1: Build module registry
+        self._build_module_registry()
+        graph.all_modules = set(self._module_paths.values())
+
+        # Step 2: Parse imports from each file
+        for dotted_name, rel_path in self._module_paths.items():
+            full_path = self.repo_path / rel_path
+            if not full_path.is_file():
+                continue
+
+            raw_imports = self._extract_imports(full_path)
+
+            # Step 3: Resolve to local modules only
+            for imp in raw_imports:
+                resolved = self._resolve_import(imp)
+                if resolved and resolved != rel_path:
+                    graph.imports[rel_path].append(resolved)
+                    graph.imported_by[resolved].append(rel_path)
+
+        # Step 4: Compute blast radius for every module
+        for module_path in graph.all_modules:
+            radius = self._compute_blast_radius(module_path, graph)
+            graph.blast_radius[module_path] = radius
+
+        logger.info(
+            "ASTAnalyzer: found %d modules, max blast radius = %d",
+            len(graph.all_modules),
+            max(graph.blast_radius.values()) if graph.blast_radius else 0,
+        )
+        return graph
+
+    # ---- module registry ----------------------------------------------------
+
+    def _build_module_registry(self) -> None:
+        """Map dotted module names → relative file paths."""
+        self._module_paths.clear()
+
+        roots = [self.repo_path]
+        src_dir = self.repo_path / "src"
+        if src_dir.is_dir():
+            roots.append(src_dir)
+
+        for root in roots:
+            for py_file in root.rglob("*.py"):
+                try:
+                    rel_to_root = py_file.relative_to(root)
+                    rel_to_repo = py_file.relative_to(self.repo_path)
+                except ValueError:
+                    continue
+
+                # Skip hidden dirs, __pycache__, venv, node_modules
+                parts = rel_to_repo.parts
+                if any(p.startswith(".") or p in ("__pycache__", "venv", ".venv", "node_modules") for p in parts):
+                    continue
+
+                rel_str = str(rel_to_repo).replace("\\", "/")
+
+                # If checking repo root and there's a src dir, skip files inside src
+                if root == self.repo_path and src_dir.is_dir() and "src" in rel_to_repo.parts:
+                    continue
+
+                # Build dotted name relative to root
+                root_parts = rel_to_root.parts
+                if rel_to_root.name == "__init__.py":
+                    dotted = ".".join(root_parts[:-1])
+                else:
+                    dotted = ".".join(root_parts[:-1] + (rel_to_root.stem,))
+
+                if dotted:
+                    self._module_paths[dotted] = rel_str
+
+    # ---- import extraction --------------------------------------------------
+
+    @staticmethod
+    def _extract_imports(filepath: Path) -> list[str]:
+        """Extract all import statements as dotted names."""
+        try:
+            source = filepath.read_text(errors="replace")
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", SyntaxWarning)
+                tree = ast.parse(source, filename=str(filepath))
+        except (SyntaxError, UnicodeDecodeError):
+            return []
+
+        imports: list[str] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    imports.append(alias.name)
+            elif isinstance(node, ast.ImportFrom):
+                if node.module:
+                    imports.append(node.module)
+        return imports
+
+    # ---- import resolution --------------------------------------------------
+
+    def _resolve_import(self, import_name: str) -> str | None:
+        """Resolve a dotted import name to a local module path, or None if external."""
+        # Try exact match
+        if import_name in self._module_paths:
+            return self._module_paths[import_name]
+
+        # Try prefix matches (e.g., "entropy.analyzers" might match "entropy.analyzers.__init__")
+        parts = import_name.split(".")
+        for i in range(len(parts), 0, -1):
+            partial = ".".join(parts[:i])
+            if partial in self._module_paths:
+                return self._module_paths[partial]
+
+        return None  # external or unresolvable
+
+    # ---- blast radius -------------------------------------------------------
+
+    def _compute_blast_radius(self, module_path: str, graph: ImportGraphData) -> int:
+        """BFS to count all transitive dependents (modules that import this, directly or indirectly)."""
+        visited: set[str] = set()
+        queue = [module_path]
+
+        while queue:
+            current = queue.pop(0)
+            for dependent in graph.imported_by.get(current, []):
+                if dependent not in visited:
+                    visited.add(dependent)
+                    queue.append(dependent)
+
+        return len(visited)