diskrx 0.1.0__py3-none-any.whl

diskrx-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: diskrx
+Version: 0.1.0
+Summary: Intelligent disk diagnostics and storage observability for SREs
+Author-email: Seshadri Naidu Vangapandu <seshuvangapandu@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Seshadri724/dxcli
+Project-URL: Repository, https://github.com/Seshadri724/dxcli
+Project-URL: Issues, https://github.com/Seshadri724/dxcli/issues
+Keywords: disk,diagnostics,sre,observability,storage,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.50
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Dynamic: license-file
+
+# 🩺 dxcli — The Disk Doctor
+
+> **Stop firefighting. Start predicting.**  
+> Replace your 45-minute disk investigation with a 30-second diagnosis.
+
+[![PyPI version](https://img.shields.io/pypi/v/dxcli.svg)](https://pypi.org/project/dxcli/)
+[![Python](https://img.shields.io/pypi/pyversions/dxcli.svg)](https://pypi.org/project/dxcli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/dxcli)](https://pypi.org/project/dxcli/)
+
+---
+
+## The Problem
+
+It's 2 AM. PagerDuty fires. Your production server is at 98% disk.
+
+You SSH in and start the ritual:
+
+```bash
+df -h          # okay, it's /var
+du -sh /var/*  # narrowing down...
+du -sh /var/log/* | sort -h  # getting warmer...
+find /var/log -size +100M    # which file?
+lsof | grep deleted          # which process?!
+```
+
+**45 minutes later**, you've found the culprit — a runaway log file from a service nobody knew was deployed. You delete it, go back to sleep, and it happens again next week.
+
+**There is a better way.**
+
+---
+
+## The Solution
+
+```bash
+dxcli diagnose /var
+```
+
+```
+🩺 Disk Doctor — Diagnosis Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚨 LOG BOMB DETECTED
+   /var/log/payments/transaction.log — 14.2 GB
+   ↳ Written by: payments-service (PID 18423)
+   ↳ Last rotation: Never
+   ↳ Prescription: Add logrotate config immediately
+
+⚠️  STALE DATA
+   /var/cache/thumbnails — 8.7 GB
+   ↳ Last accessed: 94 days ago
+   ↳ Prescription: Safe to archive or delete
+
+📈 GROWTH FORECAST
+   At current rate, /var fills in 6 hours 12 minutes
+   Growth is ACCELERATING (+340% vs last week)
+```
+
+**30 seconds. Exact culprit. Exact prescription.**
+
+---
+
+## Features
+
+### 🔍 `dxcli diagnose` — Intelligent Diagnosis
+Not just file sizes. It tells you **why** your disk is filling:
+- **Log Bomb detection** — unrotated logs growing out of control
+- **Stale file identification** — large files untouched for months
+- **Process attribution** — exactly which PID is writing to a path
+
+### 📈 `dxcli predict` — Time-to-Full Forecasting
+Linear regression on historical snapshots stored locally. Tells you:
+- When your disk will be full (hours, days, weeks)
+- Whether growth is stable or **accelerating**
+- Which directories are the fastest-growing threats
+
+### 🖥️ `dxcli dash` — Real-time TUI Dashboard
+A full terminal UI with live sparklines, anomaly alerts, and interactive process maps. No browser required.
+
+```
+┌─ Disk Overview ─────────────────────────────────┐
+│ /var    [████████████████████░░░░] 84%  ↑ FAST  │
+│ /home   [████████░░░░░░░░░░░░░░░░] 34%  → STABLE│
+│ /tmp    [███░░░░░░░░░░░░░░░░░░░░░] 12%  ↓ SLOW  │
+│                                                  │
+│ 🚨 ANOMALY: Log Bomb in /var/log/payments        │
+└──────────────────────────────────────────────────┘
+```
+
+### 🔭 `dxcli serve` — The Sentinel (Prometheus-compatible)
+Run as a background daemon. Exports `/metrics` for Grafana integration. Plug dxcli's intelligence directly into your existing observability stack.
+
+---
+
+## Installation
+
+```bash
+pip install dxcli
+```
+
+That's it. No config files. No daemons required to get started.
+
+---
+
+## Quickstart
+
+```bash
+# Diagnose a path right now
+dxcli diagnose /var
+
+# Predict when your root partition fills up
+dxcli predict /
+
+# Open the live TUI dashboard
+dxcli dash
+
+# Start the Prometheus metrics server
+dxcli serve --port 8000
+```
+
+---
+
+## How It Works
+
+dxcli stores lightweight disk snapshots in a local SQLite database (`~/.dx/history.db`). Over time, it builds a picture of your disk's growth patterns and uses linear regression to forecast the future.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    dxcli Architecture                   │
+├──────────────┬──────────────┬────────────┬─────────────┤
+│  collectors/ │  analyzers/  │   store/   │  outputs/   │
+│              │              │            │             │
+│  Raw OS data │  The "Brain" │  SQLite DB │  Rich / TUI │
+│  psutil      │  Growth rate │  Snapshots │  Prometheus │
+│  File scans  │  Anomaly     │  History   │  HTTP API   │
+│  PID mapping │  detection   │            │             │
+└──────────────┴──────────────┴────────────┴─────────────┘
+```
+
+---
+
+## Who This Is For
+
+- **SREs** who are tired of getting paged for disk full alerts they could have predicted
+- **DevOps engineers** who want disk intelligence in their Grafana dashboards
+- **Platform engineers** who need to attribute storage costs to specific services
+- **Anyone** who has typed `du -sh * | sort -h` more than once this month
+
+---
+
+## Integrations
+
+**Grafana / Prometheus**
+
+Add to your `prometheus.yml`:
+```yaml
+scrape_configs:
+  - job_name: 'dxcli'
+    static_configs:
+      - targets: ['localhost:8000']
+```
+
+Then import the dxcli dashboard from Grafana marketplace. *(Coming soon)*
+
+---
+
+## Roadmap
+
+- [ ] Grafana dashboard JSON export
+- [ ] Slack / PagerDuty alert webhooks
+- [ ] Multi-host support via SSH
+- [ ] Docker volume awareness
+- [ ] Cloud storage integration (S3 cost attribution)
+
+Have a feature request? [Open an issue](https://github.com/your-username/dxcli/issues).
+
+---
+
+## Contributing
+
+Contributions are welcome. Please read the contributing guide before submitting a PR.
+
+```bash
+git clone https://github.com/your-username/dxcli
+cd dxcli
+python -m venv venv && source venv/bin/activate
+pip install -e ".[test]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Built for SREs, by someone who got paged one too many times at 2 AM.
+</p>

diskrx-0.1.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+diskrx-0.1.0.dist-info/licenses/LICENSE,sha256=c86TVJSMxIYa5MVAOiXlAkWw5dxf4my46bpPHew0jPA,1066
+dxcli/__init__.py,sha256=JgE8MwMm8mO6Yxz4hsJBTb8TTlNgMTmRdz_-d0U-Fgg,76
+dxcli/cli.py,sha256=U4pIudskuxs_JDYQGtSBgIr1FccrM9Mz-J7HXoYMsN4,8792
+dxcli/config.py,sha256=GK17rmhIw2oWurfZIL_6Ia56GmirnCI-zm0LO3nghbo,376
+dxcli/analyzers/__init__.py,sha256=K7J4u87hagG3_rOTyb_iR4OmoQ93T9fTMoJR9fPbX2A,394
+dxcli/analyzers/anomaly.py,sha256=wksJizFtkjcOSX2c1G6OncdHVMbsM354gNdYGNn_9Q8,2206
+dxcli/analyzers/correlation.py,sha256=nYy0eyXg6Hz1Pza1bkvpUzdHMOWHBKbwFaPUknWcC68,1107
+dxcli/analyzers/growth.py,sha256=oVn-6EFLcW3qMtWNcBEeSnpNBaS4VC_ep64g2XRpaZw,2014
+dxcli/analyzers/predictor.py,sha256=MhTAYlYXJ_OPTlOSDFjGGLzGOyzUWN2tnLEtp8eoPzg,1914
+dxcli/analyzers/prescriptions.py,sha256=vrM5stRtfETeRWMkQQOruBR37ZuIsBknqEL_bpAbjg0,1967
+dxcli/analyzers/root_cause.py,sha256=qAnbs0Kr3JPCF_bmZ6XwKCXN_qaPyDe22FtKiB7bEvc,1480
+dxcli/collectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dxcli/collectors/dir_tree.py,sha256=6FkI_5ndW-JZNUVoJE9XVV9leTQerwbJLvv5wsrzXfU,2191
+dxcli/collectors/log_finder.py,sha256=z1GAQMoWr_HPDvn46qwciEYyw-Vc8cmCK6cx5DxHPqk,2073
+dxcli/collectors/process_mapper.py,sha256=2Qavu4gEb6tJBgjv-L6AUv-oHNAM6X1orCTXU097ulI,2236
+dxcli/collectors/stale_files.py,sha256=6hvMWj431yhhao5_V3wG72rT0GCtIDqPhGxqourC02k,1771
+dxcli/outputs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dxcli/outputs/cli_report.py,sha256=jpUimvxGtLOp1YA25KBUs88UXmGWcePLyPFYNLalFiQ,9592
+dxcli/outputs/metrics.py,sha256=-V6sM3AH5XUq7qiY1Db-UPCEqamdyXSyfkidFNz1UE0,1665
+dxcli/outputs/tui.py,sha256=H3U4KS7cmTOuQYP9BDddLl85uKnq_E6l7C1QSh4r3Dc,10501
+dxcli/outputs/tui.tcss,sha256=cSjyPxi9WqDp7p-HgCXdxPfIER7jQCJ4f4bdUl0rXw0,949
+dxcli/platform/__init__.py,sha256=lhEMYtqI8Cc4fCtoc7d8mKy4Jk7aqHCStHuPpZZc_QQ,380
+dxcli/platform/base.py,sha256=ika45WXYexF6ud2YbgIt5U2y0OARi0K_lzSRzQhovMk,288
+dxcli/platform/linux.py,sha256=IV1yUIl4UwwK-IvWkUG2L5kN38Acw9QemDsXip_dNYU,1001
+dxcli/platform/windows.py,sha256=IfDhZUQ0r8opZmXgeIL9xvrzGT1EaxBsjdjAmZR4NPE,966
+dxcli/store/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dxcli/store/database.py,sha256=mdkpoT9QuRGEq8k3XieXYV9Gqu6Tkf-3HHWDYucxAWw,4335
+dxcli/store/models.py,sha256=9fsYAkX-n5XKllUv_ZR20HEIlkTxL-KEht1KaV63buU,1145
+diskrx-0.1.0.dist-info/METADATA,sha256=9IgESh6mpQB0DUboNeya213WWQkiy4L3nwzJYdeFoB4,8015
+diskrx-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+diskrx-0.1.0.dist-info/entry_points.txt,sha256=snu1liBb92kyziSW6uOscR6GG-uFz1QdxKGbXK48xwg,40
+diskrx-0.1.0.dist-info/top_level.txt,sha256=_KM7grJMzPfpjdmzxvfT4RpFqLpljGEPFRK4IErTeug,6
+diskrx-0.1.0.dist-info/RECORD,,

diskrx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

diskrx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dxcli = dxcli.cli:cli

diskrx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Developer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diskrx-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dxcli

dxcli/__init__.py

@@ -0,0 +1,6 @@
+"""
+dxcli
+Intelligent disk diagnostics for SREs.
+"""
+
+__version__ = "0.1.0"

dxcli/analyzers/__init__.py

@@ -0,0 +1,15 @@
+from .growth import GrowthTracker
+from .predictor import DiskPredictor
+from .root_cause import RootCauseAnalyzer
+from .prescriptions import PrescriptionEngine
+from .correlation import CorrelationEngine
+from .anomaly import AnomalyDetector
+
+__all__ = [
+    "GrowthTracker",
+    "DiskPredictor",
+    "RootCauseAnalyzer",
+    "PrescriptionEngine",
+    "CorrelationEngine",
+    "AnomalyDetector"
+]

dxcli/analyzers/anomaly.py

@@ -0,0 +1,58 @@
+from typing import List, Dict, Optional
+from ..store.database import Database
+import time
+
+class AnomalyDetector:
+    """
+    Analyzes historical snapshots to fingerprint behavioral anomalies.
+    """
+    def __init__(self, db: Database):
+        self.db = db
+
+    def check_for_anomalies(self, path: str) -> Optional[str]:
+        """
+        Main entry point for fingerprinting. 
+        Returns a descriptive string if an anomaly is found, else None.
+        """
+        history = self.db.get_dir_history(path, limit=5) # Last 5 points
+        if len(history) < 3:
+            return None
+            
+        # 1. Check for Log Bomb (Rapid, sudden, sustained acceleration)
+        if self._is_log_bomb(history):
+            return "LOG BOMB: Rapid, sustained write spike detected."
+            
+        # 2. Check for Persistent Leak (Small but never-ending growth)
+        if self._is_leak(history):
+            return "LEAK: Steady growth over several hours with no cleanup."
+            
+        return None
+
+    def _is_log_bomb(self, history: List[Dict]) -> bool:
+        # Simplistic check: If last growth is > 5x the average of previous points
+        deltas = []
+        for i in range(len(history)-1):
+            deltas.append(max(0, history[i+1]['size_bytes'] - history[i]['size_bytes']))
+            
+        if len(deltas) < 2: return False
+        
+        last_delta = deltas[-1]
+        avg_prev_delta = sum(deltas[:-1]) / len(deltas[:-1])
+        
+        # If it's a massive jump (e.g., 10x) and substantial (>10MB)
+        if last_delta > (avg_prev_delta * 10) and last_delta > 1024 * 1024 * 10:
+            return True
+        return False
+
+    def _is_leak(self, history: List[Dict]) -> bool:
+        # Check if EVERY delta in the last 5 points is positive (no drops)
+        deltas = []
+        for i in range(len(history)-1):
+            deltas.append(history[i+1]['size_bytes'] - history[i]['size_bytes'])
+            
+        if all(d > 0 for d in deltas) and len(deltas) >= 4:
+            # If total growth over this time is > 1MB (avoid noise)
+            total_change = sum(deltas)
+            if total_change > 1024 * 1024:
+                return True
+        return False

dxcli/analyzers/correlation.py

@@ -0,0 +1,32 @@
+from typing import List, Dict
+from ..store.models import DirNode
+from ..collectors.process_mapper import ProcessMapper, ProcessRef
+
+class CorrelationEngine:
+    """
+    Bridges the gap between the growth analyzer and the process list.
+    """
+    def __init__(self):
+        self.mapper = ProcessMapper()
+
+    def correlate(self, growing_dirs: List[Dict]) -> List[Dict]:
+        """
+        Takes a list of growth results from RootCauseAnalyzer and attempts 
+        to attribute a PID to each growing directory.
+        """
+        results = []
+        for g in growing_dirs:
+            # We only look for culprits if the trend is not "Stable"
+            res = g.copy()
+            res["culprit"] = None
+            
+            if g["trend"] != "Stable":
+                culprits = self.mapper.find_culprits(g["path"])
+                if culprits:
+                    # Pick the first one or prioritize by name match?
+                    # For now just the first one found
+                    res["culprit"] = culprits[0]
+            
+            results.append(res)
+            
+        return results

dxcli/analyzers/growth.py

@@ -0,0 +1,53 @@
+from ..store.database import Database
+from ..store.models import GrowthRate
+from typing import Optional
+import numpy as np
+import warnings
+
+class GrowthTracker:
+    """
+    Calculates daily growth rate per directory based on historical SQLite snapshots.
+    """
+    def __init__(self, db: Database):
+        self.db = db
+
+    def get_growth_rate(self, path: str, days: int = 7) -> Optional[GrowthRate]:
+        history = self.db.get_dir_history(path, days_back=days)
+        if len(history) < 2:
+            return None # Not enough history
+
+        # Extract timestamps and sizes
+        timestamps = np.array([h['timestamp'] for h in history])
+        sizes = np.array([h['size_bytes'] for h in history])
+        
+        # Linear regression: size = m * timestamp + c
+        # We want m (bytes per second)
+        # Polyfit returns [m, c] for deg=1
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', np.exceptions.RankWarning)
+            try:
+                m, _ = np.polyfit(timestamps, sizes, 1)
+            except np.exceptions.RankWarning:
+                return None  # Data too noisy/flat for reliable regression
+        
+        # Convert bytes per second to bytes per day
+        bytes_per_day = m * 86400.0
+        
+        return GrowthRate(path=path, bytes_per_day=bytes_per_day)
+
+    def get_partition_growth_rate(self, mountpoint: str, days: int = 7) -> float:
+        """Returns bytes per day growth for a whole partition."""
+        history = self.db.get_history(mountpoint, days_back=days)
+        if len(history) < 2:
+            return 0.0
+
+        timestamps = np.array([h['timestamp'] for h in history])
+        sizes = np.array([h['used_bytes'] for h in history])
+        
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', np.exceptions.RankWarning)
+            try:
+                m, _ = np.polyfit(timestamps, sizes, 1)
+            except np.exceptions.RankWarning:
+                return 0.0
+        return m * 86400.0

dxcli/analyzers/predictor.py

@@ -0,0 +1,44 @@
+import time
+from typing import Optional
+from .growth import GrowthTracker
+from ..store.models import PredictionResult, Partition
+from ..store.database import Database
+
+class DiskPredictor:
+    """
+    Linear regression on historical usage data to determine time-to-full.
+    """
+    def __init__(self, db: Database):
+        self.tracker = GrowthTracker(db)
+
+    def predict_full_date(self, partition: Partition) -> Optional[PredictionResult]:
+        daily_growth = self.tracker.get_partition_growth_rate(partition.mountpoint)
+        
+        if daily_growth <= 1024 * 1024:  # Less than 1MB/day is considered roughly stable/static
+            return PredictionResult(
+                path=partition.mountpoint,
+                date_full_timestamp=None,
+                days_until_full=None,
+                current_capacity_bytes=partition.total_bytes,
+                current_usage_bytes=partition.used_bytes,
+                daily_growth_bytes=daily_growth,
+                is_accelerating=False
+            )
+
+        remaining_bytes = partition.total_bytes - partition.used_bytes
+        days_until_full = remaining_bytes / daily_growth
+        
+        # Super simple acceleration check (compare last 3 days vs last 7 days)
+        short_growth = self.tracker.get_partition_growth_rate(partition.mountpoint, days=3)
+        long_growth = self.tracker.get_partition_growth_rate(partition.mountpoint, days=7)
+        is_accelerating = short_growth > (long_growth * 1.2) # 20% spike is accelerating
+        
+        return PredictionResult(
+            path=partition.mountpoint,
+            date_full_timestamp=time.time() + (days_until_full * 86400),
+            days_until_full=days_until_full,
+            current_capacity_bytes=partition.total_bytes,
+            current_usage_bytes=partition.used_bytes,
+            daily_growth_bytes=daily_growth,
+            is_accelerating=is_accelerating
+        )

dxcli/analyzers/prescriptions.py

@@ -0,0 +1,61 @@
+import os
+import sys
+from typing import List
+from ..store.models import Prescription, UnrotatedLog, StaleFile
+
+class PrescriptionEngine:
+    """
+    Pattern-matched remediation recommendations.
+    """
+    def __init__(self):
+        pass
+
+    def synthesize(self, logs: List[UnrotatedLog], stales: List[StaleFile]) -> List[Prescription]:
+        prescriptions = []
+        is_windows = sys.platform == "win32"
+        
+        # Log Prescriptions
+        for i, log in enumerate(logs):
+            if not log.has_logrotate_config:
+                service_name = os.path.basename(log.path).replace('.log', '')
+                if not service_name:
+                    service_name = "custom_service"
+                
+                if is_windows:
+                    template = f"# Windows does not have logrotate.\n# Manually archive or delete: {log.path}"
+                    name = f"Archive log for {service_name}"
+                else:
+                    template = f"""# /etc/logrotate.d/{service_name}
+{log.path} {{
+    daily
+    rotate 7
+    compress
+    missingok
+    copytruncate
+}}"""
+                    name = f"Add logrotate for {service_name}"
+
+                prescriptions.append(Prescription(
+                    id=f"log_{i}",
+                    name=name,
+                    template=template,
+                    risk="safe",
+                    size_savings_bytes=log.size_bytes
+                ))
+
+        # Stale Prescriptions
+        for i, stale in enumerate(stales):
+            if is_windows:
+                cmd = f"Remove-Item -Force '{stale.path}'"
+            else:
+                cmd = f"rm -f '{stale.path}'"
+
+            prescriptions.append(Prescription(
+                id=f"stale_{i}",
+                name=f"Remove stale file: {os.path.basename(stale.path)}",
+                template=cmd,
+                risk="needs-review",
+                size_savings_bytes=stale.size_bytes
+            ))
+
+        return prescriptions

dxcli/analyzers/root_cause.py

@@ -0,0 +1,41 @@
+from typing import List, Dict
+from ..store.models import DirNode
+from .growth import GrowthTracker
+from ..store.database import Database
+
+class RootCauseAnalyzer:
+    """
+    Ranks directories by absolute growth velocity (change) rather than sheer size.
+    """
+    def __init__(self, db: Database):
+        self.tracker = GrowthTracker(db)
+
+    def attribute_cause(self, top_dirs: List[DirNode], days: int = 7) -> List[Dict]:
+        """
+        Takes the top N directories, queries their historical growth, 
+        and sorts them by who is growing the fastest.
+        """
+        results = []
+        for d in top_dirs:
+            rate = self.tracker.get_growth_rate(d.path, days=days)
+            velocity = rate.bytes_per_day if rate else 0.0
+            
+            # Simple trend string
+            trend_str = "Stable"
+            if velocity > 1024 * 1024 * 50: # >50MB/day
+                trend_str = "Spiking ↑"
+            elif velocity > 1024 * 1024 * 5: # >5MB/day
+                trend_str = "Growing ↗"
+            elif velocity < -1024 * 1024:
+                trend_str = "Shrinking ↘"
+                
+            results.append({
+                "path": d.path,
+                "current_size": d.size_bytes,
+                "velocity_per_day": velocity,
+                "trend": trend_str
+            })
+            
+        # Sort by fastest growing first
+        results.sort(key=lambda x: x["velocity_per_day"], reverse=True)
+        return results