icdev 0.0.3__py3-none-any.whl

tools/analytics/scorecard.py

@@ -0,0 +1,538 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Developer / Project Health Scorecard.
+
+Aggregates code quality, security, compliance, test coverage, velocity,
+and Secure by Design posture into a weighted composite score with letter
+grades.  Stores append-only snapshots for trend tracking.
+
+Dimension weights (updated for SbD — Cloudyrion P6 Risk-Driven):
+    code_quality  = 0.20
+    security      = 0.20
+    compliance    = 0.15
+    test_coverage = 0.15
+    velocity      = 0.10
+    sbd_posture   = 0.20
+
+Letter grades: A >= 90, B >= 80, C >= 70, D >= 60, F < 60.
+
+Tables used:
+  - developer_scorecards   (write scorecard snapshots)
+  - code_quality_metrics   (read latest maintainability score)
+  - project_controls       (read compliance implementation status)
+  - audit_trail            (read security/test events)
+  - vsm_dora_snapshots     (read deployment frequency)
+
+CLI:
+  python tools/analytics/scorecard.py --project-id <id> --compute --json
+  python tools/analytics/scorecard.py --project-id <id> --trend --json
+  python tools/analytics/scorecard.py --project-id <id> --latest --json
+"""
+
+import argparse
+import json
+import sqlite3
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+DB_PATH = BASE_DIR / "data" / "icdev.db"
+
+try:
+    from tools.compat.db_utils import get_db_connection
+except ImportError:
+    get_db_connection = None
+
+# ---------------------------------------------------------------------------
+# Weights and grades
+# ---------------------------------------------------------------------------
+
+DIMENSION_WEIGHTS = {
+    "code_quality": 0.20,
+    "security": 0.20,
+    "compliance": 0.15,
+    "test_coverage": 0.15,
+    "velocity": 0.10,
+    "sbd_posture": 0.20,
+}
+
+_GRADE_THRESHOLDS = [
+    (90, "A"),
+    (80, "B"),
+    (70, "C"),
+    (60, "D"),
+]
+
+
+def _letter_grade(score: float) -> str:
+    for threshold, grade in _GRADE_THRESHOLDS:
+        if score >= threshold:
+            return grade
+    return "F"
+
+
+# ---------------------------------------------------------------------------
+# Database helpers
+# ---------------------------------------------------------------------------
+
+def _get_connection(db_path=None):
+    """Return a sqlite3 connection with Row factory.
+
+    Tries tools.compat.db_utils first, falls back to direct connect.
+    """
+    if db_path is None and get_db_connection is not None:
+        try:
+            conn = get_db_connection()
+            conn.row_factory = sqlite3.Row
+            return conn
+        except Exception:
+            pass
+    path = Path(db_path) if db_path else DB_PATH
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Database not found: {path}\n"
+            "Run: python tools/db/init_icdev_db.py"
+        )
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def _ensure_tables(conn):
+    """Create scorecard table if it does not exist."""
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS developer_scorecards ("
+        "id TEXT PRIMARY KEY, "
+        "project_id TEXT NOT NULL, "
+        "actor TEXT, "
+        "overall_score REAL NOT NULL, "
+        "letter_grade TEXT NOT NULL, "
+        "dimensions TEXT, "
+        "created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)"
+    )
+    conn.commit()
+
+
+def _log_audit(conn, project_id, event_type, action, details):
+    """Append-only audit trail entry (INSERT only — NIST AU)."""
+    try:
+        conn.execute(
+            "INSERT INTO audit_trail "
+            "(project_id, event_type, actor, action, details, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (
+                project_id,
+                event_type,
+                "sparkpilot-scorecard",
+                action,
+                json.dumps(details) if isinstance(details, dict) else str(details),
+                datetime.now(timezone.utc).isoformat(),
+            ),
+        )
+        conn.commit()
+    except Exception as exc:
+        print(f"Warning: audit log failed: {exc}", file=sys.stderr)
+
+
+def _uid() -> str:
+    return uuid.uuid4().hex[:12]
+
+
+# ---------------------------------------------------------------------------
+# Dimension scoring helpers
+# ---------------------------------------------------------------------------
+
+def _score_code_quality(conn, project_id: str) -> Dict[str, Any]:
+    """Score from code_quality_metrics.maintainability_score (latest)."""
+    try:
+        row = conn.execute(
+            "SELECT maintainability_score FROM code_quality_metrics "
+            "WHERE project_id = ? ORDER BY created_at DESC LIMIT 1",
+            (project_id,),
+        ).fetchone()
+        if row and row["maintainability_score"] is not None:
+            score = min(max(float(row["maintainability_score"]), 0.0), 100.0)
+            return {"score": round(score, 1), "details": "From code_quality_metrics"}
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No code quality data — default 50"}
+
+
+def _score_security(conn, project_id: str) -> Dict[str, Any]:
+    """Score = 100 - (critical*20 + high*10 + medium*3) from recent security scans."""
+    try:
+        rows = conn.execute(
+            "SELECT details FROM audit_trail "
+            "WHERE project_id = ? AND event_type = 'security_scan' "
+            "AND created_at >= datetime('now', '-30 days')",
+            (project_id,),
+        ).fetchall()
+        critical = 0
+        high = 0
+        medium = 0
+        for r in rows:
+            try:
+                d = json.loads(r["details"]) if r["details"] else {}
+            except (json.JSONDecodeError, TypeError):
+                d = {}
+            critical += int(d.get("critical", 0))
+            high += int(d.get("high", 0))
+            medium += int(d.get("medium", 0))
+        raw = 100 - (critical * 20 + high * 10 + medium * 3)
+        score = max(raw, 0.0)
+        return {
+            "score": round(min(score, 100.0), 1),
+            "details": f"critical={critical}, high={high}, medium={medium}",
+        }
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No security scan data — default 50"}
+
+
+def _score_compliance(conn, project_id: str) -> Dict[str, Any]:
+    """Score = % of project_controls with status='implemented'."""
+    try:
+        total_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM project_controls WHERE project_id = ?",
+            (project_id,),
+        ).fetchone()
+        total = int(total_row["cnt"]) if total_row else 0
+        if total == 0:
+            return {"score": 50.0, "details": "No controls defined — default 50"}
+        impl_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM project_controls "
+            "WHERE project_id = ? AND status = 'implemented'",
+            (project_id,),
+        ).fetchone()
+        implemented = int(impl_row["cnt"]) if impl_row else 0
+        pct = (implemented / total) * 100.0
+        return {
+            "score": round(min(pct, 100.0), 1),
+            "details": f"{implemented}/{total} controls implemented",
+        }
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No compliance data — default 50"}
+
+
+def _score_test_coverage(conn, project_id: str) -> Dict[str, Any]:
+    """Score = pass_rate * 100 from audit_trail test events (last 30 days)."""
+    try:
+        rows = conn.execute(
+            "SELECT event_type FROM audit_trail "
+            "WHERE project_id = ? AND event_type IN ('test_passed', 'test_failed') "
+            "AND created_at >= datetime('now', '-30 days')",
+            (project_id,),
+        ).fetchall()
+        if not rows:
+            return {"score": 50.0, "details": "No test events — default 50"}
+        passed = sum(1 for r in rows if r["event_type"] == "test_passed")
+        total = len(rows)
+        rate = (passed / total) * 100.0
+        return {
+            "score": round(min(rate, 100.0), 1),
+            "details": f"{passed}/{total} tests passed",
+        }
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No test data — default 50"}
+
+
+def _score_velocity(conn, project_id: str) -> Dict[str, Any]:
+    """Score = min(deployment_frequency * 20, 100) from vsm_dora_snapshots."""
+    try:
+        row = conn.execute(
+            "SELECT deployment_frequency FROM vsm_dora_snapshots "
+            "WHERE project_id = ? ORDER BY created_at DESC LIMIT 1",
+            (project_id,),
+        ).fetchone()
+        if row and row["deployment_frequency"] is not None:
+            freq = float(row["deployment_frequency"])
+            score = min(freq * 20.0, 100.0)
+            return {
+                "score": round(score, 1),
+                "details": f"deployment_frequency={round(freq, 4)}/day",
+            }
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No DORA data — default 50"}
+
+
+def _score_sbd_posture(conn, project_id: str) -> Dict[str, Any]:
+    """Score from sbd_assessments: % of requirements satisfied or partially satisfied.
+
+    Also factors in exception aging from sbd_exceptions table.
+    Cloudyrion P6: Risk-Driven Prioritization via SbD posture measurement.
+    """
+    try:
+        total_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM sbd_assessments WHERE project_id = ?",
+            (project_id,),
+        ).fetchone()
+        total = int(total_row["cnt"]) if total_row else 0
+        if total == 0:
+            return {"score": 50.0, "details": "No SbD assessment data -- default 50"}
+
+        sat_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM sbd_assessments "
+            "WHERE project_id = ? AND status = 'satisfied'",
+            (project_id,),
+        ).fetchone()
+        partial_row = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM sbd_assessments "
+            "WHERE project_id = ? AND status = 'partially_satisfied'",
+            (project_id,),
+        ).fetchone()
+        satisfied = int(sat_row["cnt"]) if sat_row else 0
+        partial = int(partial_row["cnt"]) if partial_row else 0
+
+        # Satisfied = full credit, partially = half credit
+        raw = ((satisfied + partial * 0.5) / total) * 100.0
+
+        # Penalize expired exceptions (Cloudyrion P8: no lingering exceptions)
+        try:
+            expired_row = conn.execute(
+                "SELECT COUNT(*) AS cnt FROM sbd_exceptions "
+                "WHERE project_id = ? AND status = 'active' "
+                "AND expires_at < datetime('now')",
+                (project_id,),
+            ).fetchone()
+            expired = int(expired_row["cnt"]) if expired_row else 0
+            raw -= expired * 5  # -5 points per expired exception
+        except Exception:
+            expired = 0
+
+        score = max(min(raw, 100.0), 0.0)
+        return {
+            "score": round(score, 1),
+            "details": (
+                f"{satisfied}/{total} satisfied, {partial} partial"
+                + (f", {expired} expired exceptions (-{expired * 5}pts)"
+                   if expired else "")
+            ),
+        }
+    except Exception:
+        pass
+    return {"score": 50.0, "details": "No SbD data -- default 50"}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def compute_scorecard(project_id: str, actor: Optional[str] = None, db_path=None) -> dict:
+    """Compute a weighted composite scorecard across 5 dimensions.
+
+    Args:
+        project_id: Project identifier.
+        actor: Optional actor/developer name.
+        db_path: Optional database path override.
+
+    Returns:
+        dict with id, project_id, actor, overall_score, letter_grade,
+        and per-dimension breakdowns.
+    """
+    conn = _get_connection(db_path)
+    try:
+        _ensure_tables(conn)
+
+        dimensions = {
+            "code_quality": _score_code_quality(conn, project_id),
+            "security": _score_security(conn, project_id),
+            "compliance": _score_compliance(conn, project_id),
+            "test_coverage": _score_test_coverage(conn, project_id),
+            "velocity": _score_velocity(conn, project_id),
+            "sbd_posture": _score_sbd_posture(conn, project_id),
+        }
+
+        overall = 0.0
+        for dim_name, weight in DIMENSION_WEIGHTS.items():
+            overall += dimensions[dim_name]["score"] * weight
+        overall = round(min(max(overall, 0.0), 100.0), 1)
+        grade = _letter_grade(overall)
+
+        scorecard_id = _uid()
+        conn.execute(
+            "INSERT INTO developer_scorecards "
+            "(id, project_id, actor, overall_score, letter_grade, dimensions, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                scorecard_id,
+                project_id,
+                actor,
+                overall,
+                grade,
+                json.dumps(dimensions),
+                datetime.now(timezone.utc).isoformat(),
+            ),
+        )
+        conn.commit()
+
+        _log_audit(conn, project_id, "scorecard_computed",
+                   f"Scorecard computed: {overall} ({grade})",
+                   {"scorecard_id": scorecard_id, "overall_score": overall,
+                    "letter_grade": grade, "actor": actor})
+
+        return {
+            "id": scorecard_id,
+            "project_id": project_id,
+            "actor": actor,
+            "overall_score": overall,
+            "letter_grade": grade,
+            "dimensions": dimensions,
+        }
+    finally:
+        conn.close()
+
+
+def get_trend(project_id: str, limit: int = 20, db_path=None) -> dict:
+    """Return recent scorecard snapshots for trend analysis.
+
+    Args:
+        project_id: Project identifier.
+        limit: Maximum number of snapshots (default 20).
+        db_path: Optional database path override.
+
+    Returns:
+        dict with project_id, snapshots list, and count.
+    """
+    conn = _get_connection(db_path)
+    try:
+        _ensure_tables(conn)
+        rows = conn.execute(
+            "SELECT id, overall_score, letter_grade, created_at "
+            "FROM developer_scorecards "
+            "WHERE project_id = ? "
+            "ORDER BY created_at DESC LIMIT ?",
+            (project_id, limit),
+        ).fetchall()
+
+        snapshots = [
+            {
+                "id": r["id"],
+                "overall_score": r["overall_score"],
+                "letter_grade": r["letter_grade"],
+                "created_at": r["created_at"],
+            }
+            for r in rows
+        ]
+
+        return {
+            "project_id": project_id,
+            "snapshots": snapshots,
+            "count": len(snapshots),
+        }
+    finally:
+        conn.close()
+
+
+def get_latest(project_id: str, db_path=None) -> Optional[dict]:
+    """Return the most recent scorecard or None.
+
+    Args:
+        project_id: Project identifier.
+        db_path: Optional database path override.
+
+    Returns:
+        dict with scorecard data or None if no scorecards exist.
+    """
+    conn = _get_connection(db_path)
+    try:
+        _ensure_tables(conn)
+        row = conn.execute(
+            "SELECT id, project_id, actor, overall_score, letter_grade, "
+            "dimensions, created_at "
+            "FROM developer_scorecards "
+            "WHERE project_id = ? "
+            "ORDER BY created_at DESC LIMIT 1",
+            (project_id,),
+        ).fetchone()
+
+        if not row:
+            return None
+
+        dims = {}
+        try:
+            dims = json.loads(row["dimensions"]) if row["dimensions"] else {}
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+        return {
+            "id": row["id"],
+            "project_id": row["project_id"],
+            "actor": row["actor"],
+            "overall_score": row["overall_score"],
+            "letter_grade": row["letter_grade"],
+            "dimensions": dims,
+            "created_at": row["created_at"],
+        }
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Developer / Project Health Scorecard"
+    )
+    parser.add_argument("--project-id", required=True, help="Project identifier")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    parser.add_argument("--compute", action="store_true",
+                        help="Compute a new scorecard")
+    parser.add_argument("--actor", help="Actor/developer name (with --compute)")
+
+    parser.add_argument("--trend", action="store_true",
+                        help="Show scorecard trend")
+    parser.add_argument("--limit", type=int, default=20,
+                        help="Max snapshots for trend (default 20)")
+
+    parser.add_argument("--latest", action="store_true",
+                        help="Show latest scorecard")
+
+    args = parser.parse_args()
+
+    try:
+        if args.compute:
+            result = compute_scorecard(
+                project_id=args.project_id,
+                actor=args.actor,
+            )
+        elif args.trend:
+            result = get_trend(
+                project_id=args.project_id,
+                limit=args.limit,
+            )
+        elif args.latest:
+            result = get_latest(project_id=args.project_id)
+            if result is None:
+                result = {"project_id": args.project_id, "scorecard": None,
+                          "message": "No scorecards found"}
+        else:
+            parser.print_help()
+            sys.exit(1)
+
+        if args.json:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            for key, value in result.items():
+                print(f"{key}: {value}")
+
+    except Exception as exc:
+        err = {"error": str(exc)}
+        if args.json:
+            print(json.dumps(err, indent=2))
+        else:
+            print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()