rune/scripts/graph_health_report.py

#!/usr/bin/env python3
"""graph_health_report.py — #42: the live graph-memory health instrument.

Replaces the stale dossier statistic with a live report: superseded /
active / expired edge ratios, orphan rates, normalization behavior —
against ANY store path (default: the repo-local memory store). A store
with no edges reports no-data, never 0%.

Usage: python3 scripts/graph_health_report.py [--store PATH] [--json]
"""

import argparse
import json
import sqlite3
import sys
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent
sys.path.insert(0, str(REPO / "src"))
sys.path.insert(0, str(REPO / "src" / "rune"))

DEFAULT_STORE = REPO / "memory" / "store" / "memory.db"


def report(store_path):
    store_path = Path(store_path)
    if not store_path.exists():
        return {"store": str(store_path), "status": "no-store",
                "note": "no database at this path"}
    db = sqlite3.connect(f"file:{store_path}?mode=ro", uri=True)
    db.row_factory = sqlite3.Row
    try:
        tables = {r[0] for r in db.execute(
            "SELECT name FROM sqlite_master WHERE type='table'").fetchall()}
    except Exception as e:  # noqa: BLE001 — deliberate: unreadable store reports as unreadable, never crashes
        return {"store": str(store_path), "status": "unreadable",
                "note": str(e)}
    out = {"store": str(store_path), "status": "ok", "tables": sorted(tables)}
    if "edges" not in tables:
        out["status"] = "no-graph"
        out["note"] = "no edges table — not a graph store"
        return out
    try:
        total = db.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
    except Exception as e:  # noqa: BLE001 — deliberate: corrupt edges table reports as unreadable
        out["status"] = "unreadable"
        out["note"] = str(e)
        return out
    if total == 0:
        out["status"] = "no-data"
        out["note"] = ("empty graph: ratios are undefined, not 0% — "
                       "the dossier statistic cannot be confirmed or denied")
        out["edges"] = {"total": 0}
        return out

    def count(where):
        return db.execute(f"SELECT COUNT(*) FROM edges WHERE {where}").fetchone()[0]

    active = count("status='active'")
    superseded = count("status='superseded'")
    expired = count("status='expired'")
    orphan = db.execute(
        "SELECT COUNT(*) FROM edges WHERE superseded_by IS NOT NULL "
        "AND superseded_by NOT IN (SELECT id FROM edges)").fetchone()[0]
    dangling = db.execute(
        "SELECT COUNT(*) FROM edges WHERE subj_id NOT IN "
        "(SELECT id FROM entities) OR obj_id NOT IN "
        "(SELECT id FROM entities)").fetchone()[0]
    out["edges"] = {
        "total": total,
        "active": active,
        "superseded": superseded,
        "expired": expired,
        "active_ratio": round(active / total, 4),
        "superseded_ratio": round(superseded / total, 4),
        "expired_ratio": round(expired / total, 4),
        "orphan_superseded_by": orphan,
        "dangling_endpoints": dangling,
    }
    # normalization behavior: distinct predicates vs edges
    out["normalization"] = {
        "distinct_predicates": db.execute(
            "SELECT COUNT(DISTINCT pred) FROM edges").fetchone()[0],
    }
    return out


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--store", default=str(DEFAULT_STORE))
    ap.add_argument("--json", action="store_true")
    args = ap.parse_args()
    rep = report(args.store)
    if args.json:
        print(json.dumps(rep, indent=1))
    else:
        print(f"store: {rep['store']}")
        print(f"status: {rep['status']}")
        if rep["status"] == "ok":
            e = rep["edges"]
            print(f"edges: {e['total']} (active {e['active_ratio']}, "
                  f"superseded {e['superseded_ratio']}, expired {e['expired_ratio']})")
            print(f"orphans: {e['orphan_superseded_by']}, "
                  f"dangling: {e['dangling_endpoints']}")
        else:
            print(f"note: {rep.get('note', '')}")
    return 0


if __name__ == "__main__":
    sys.exit(main())