diff --git a/.eslintrc.json b/.eslintrc.json index 957cd154..f7d94cd2 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -1,3 +1,4 @@ { + "root": true, "extends": ["next/core-web-vitals"] } diff --git a/src/app/dashboard/page.tsx b/src/app/dashboard/page.tsx index 3c7a6a7d..dda77795 100644 --- a/src/app/dashboard/page.tsx +++ b/src/app/dashboard/page.tsx @@ -1,4 +1,4 @@ -import TodayFocusHero from "@/components/TodayFocusHero"; +import TodayFocusHero from "@/components/TodayFocusHero"; import DashboardHeader from "@/components/DashboardHeader"; import ExportButton from "@/components/ExportButton"; import Link from "next/link"; @@ -20,9 +20,7 @@ export default async function DashboardPage() {
- {/* Quick actions */}
- {/* Left side actions */}
+
+
+
+
+ + Interactive + + + Repo Health + +
+

+ Repository Health Explorer +

+

+ Radar charts, score breakdowns, and automated recommendations + for your most active repositories. +

+
+ + Explore Health + + +
+
+
); -} \ No newline at end of file +} diff --git a/src/app/dashboard/repo-health/page.tsx b/src/app/dashboard/repo-health/page.tsx new file mode 100644 index 00000000..2e639973 --- /dev/null +++ b/src/app/dashboard/repo-health/page.tsx @@ -0,0 +1,16 @@ +import { getServerSession } from "next-auth"; +import { authOptions } from "@/lib/auth"; +import { redirect } from "next/navigation"; +import RepoHealthExplorer from "@/components/repo-health/RepoHealthExplorer"; + +export const metadata = { + title: "Repository Health Explorer — DevTrack", + description: + "Interactive health breakdown, radar chart, score analysis, and recommendations for your most active GitHub repositories.", +}; + +export default async function RepoHealthPage() { + const session = await getServerSession(authOptions); + if (!session) redirect("/"); + return ; +} diff --git a/src/components/RepoHealthPanel.tsx b/src/components/RepoHealthPanel.tsx index f622116b..663577f9 100644 --- a/src/components/RepoHealthPanel.tsx +++ b/src/components/RepoHealthPanel.tsx @@ -91,9 +91,17 @@ export default function RepoHealthPanel({ health, isOpen, onClose }: Props) {
))}
-

- Score based on activity in the last 30 days. Updates on page refresh. -

+
+

+ Score based on activity in the last 30 days. Updates on page refresh. +

+ + Full Analysis → + +
); diff --git a/src/components/repo-health/RepoHealthBreakdown.tsx b/src/components/repo-health/RepoHealthBreakdown.tsx new file mode 100644 index 00000000..5580815d --- /dev/null +++ b/src/components/repo-health/RepoHealthBreakdown.tsx @@ -0,0 +1,101 @@ +"use client"; + +import { memo } from "react"; +import type { BreakdownRow } from "@/lib/repo-health-insights"; + +interface Props { + rows: BreakdownRow[]; +} + +function ScoreBar({ pct }: { pct: number }) { + const color = + pct >= 70 + ? "bg-[var(--accent)]" + : pct >= 40 + ? "bg-[#ca8a04]" + : "bg-[var(--destructive)]"; + + return ( +
+
+
+ ); +} + +/** + * Tabular breakdown of the five health-score dimensions. + * + * Each row shows: + * – Metric label + * – Raw signal value (formatted) + * – Earned / max score + * – Progress bar proportional to earned / max + * – Weight contribution to the 100-point total + * – Tooltip with target description + */ +function RepoHealthBreakdown({ rows }: Props) { + return ( +
+

+ Score Breakdown +

+ +
+ {rows.map((row) => { + const pct = Math.round((row.earned / row.maxScore) * 100); + return ( +
+
+ {/* Metric name + tooltip */} + + {row.label} + + + + {/* Raw signal value */} + + {row.rawValue} + + + {/* Earned / max */} + + + {row.earned} + + /{row.maxScore} + + ({row.weightPct}%) + + + +
+ + +
+ ); + })} +
+ +

+ Hover metric names for target thresholds. Total weight: 100 pts. +

+
+ ); +} + +export default memo(RepoHealthBreakdown); diff --git a/src/components/repo-health/RepoHealthCard.tsx b/src/components/repo-health/RepoHealthCard.tsx new file mode 100644 index 00000000..5e66e587 --- /dev/null +++ b/src/components/repo-health/RepoHealthCard.tsx @@ -0,0 +1,93 @@ +"use client"; + +import { memo } from "react"; +import type { RepoHealthScore } from "@/types/repo-health"; +import { gradeLetter, gradeLabel } from "@/lib/repo-health-insights"; + +interface Props { + health: RepoHealthScore; + isSelected: boolean; + onClick: () => void; +} + +const GRADE_BADGE: Record = { + green: + "bg-[var(--accent)]/15 text-[var(--accent)] border-[var(--accent)]/25", + yellow: "bg-[#ca8a04]/15 text-[#ca8a04] border-[#ca8a04]/25", + red: "bg-[var(--destructive)]/15 text-[var(--destructive)] border-[var(--destructive)]/25", +}; + +const GRADE_RING: Record = { + green: "ring-[var(--accent)]", + yellow: "ring-[#ca8a04]", + red: "ring-[var(--destructive)]", +}; + +/** + * Compact repo card used in the explorer's left-panel repo list. + * + * Displays the repository name, letter grade, numeric score, and a small + * progress bar. Clicking selects the repo and shows the detailed breakdown. + */ +function RepoHealthCard({ health, isSelected, onClick }: Props) { + const shortName = health.repo.split("/")[1] ?? health.repo; + const letter = gradeLetter(health.score); + const label = gradeLabel(health.grade); + const badgeClass = GRADE_BADGE[health.grade] ?? GRADE_BADGE.red; + const ringClass = GRADE_RING[health.grade] ?? GRADE_RING.red; + + return ( + + ); +} + +export default memo(RepoHealthCard); diff --git a/src/components/repo-health/RepoHealthExplorer.tsx b/src/components/repo-health/RepoHealthExplorer.tsx new file mode 100644 index 00000000..0d6a40f5 --- /dev/null +++ b/src/components/repo-health/RepoHealthExplorer.tsx @@ -0,0 +1,390 @@ +"use client"; + +import { useCallback, useEffect, useMemo, useState, memo } from "react"; +import dynamic from "next/dynamic"; +import Link from "next/link"; +import { ArrowLeft, ExternalLink, RefreshCw } from "lucide-react"; +import { useAccount } from "@/components/AccountContext"; +import type { RepoHealthScore } from "@/types/repo-health"; +import { + buildBreakdown, + buildRadarData, + generateInsights, + gradeLetter, + gradeLabel, +} from "@/lib/repo-health-insights"; +import RepoHealthCard from "@/components/repo-health/RepoHealthCard"; +import RepoHealthBreakdown from "@/components/repo-health/RepoHealthBreakdown"; +import RepoHealthInsights from "@/components/repo-health/RepoHealthInsights"; + +// Lazy-load recharts-backed components so the charting bundle is only fetched +// when the explorer page is actually visited. +const RepoHealthGauge = dynamic( + () => import("@/components/repo-health/RepoHealthGauge"), + { + ssr: false, + loading: () => ( +
+
+
+ ), + } +); + +const RepoHealthRadar = dynamic( + () => import("@/components/repo-health/RepoHealthRadar"), + { + ssr: false, + loading: () => ( +
+ ), + } +); + +// --------------------------------------------------------------------------- +// Grade styling +// --------------------------------------------------------------------------- + +const GRADE_COLOR: Record = { + green: "text-[var(--accent)]", + yellow: "text-[#ca8a04]", + red: "text-[var(--destructive)]", +}; + +const GRADE_BG: Record = { + green: "border-[var(--accent)]/30 bg-[var(--accent)]/8", + yellow: "border-[#ca8a04]/30 bg-[#ca8a04]/8", + red: "border-[var(--destructive)]/30 bg-[var(--destructive)]/8", +}; + +// --------------------------------------------------------------------------- +// Detail panel +// --------------------------------------------------------------------------- + +interface DetailPanelProps { + health: RepoHealthScore; +} + +const DetailPanel = memo(function DetailPanel({ health }: DetailPanelProps) { + const letter = gradeLetter(health.score); + const label = gradeLabel(health.grade); + const shortName = health.repo.split("/")[1] ?? health.repo; + const radarData = useMemo(() => buildRadarData(health.signals), [health]); + const breakdown = useMemo(() => buildBreakdown(health.signals), [health]); + const insights = useMemo(() => generateInsights(health.signals), [health]); + const colorClass = GRADE_COLOR[health.grade] ?? GRADE_COLOR.red; + const bgClass = GRADE_BG[health.grade] ?? GRADE_BG.red; + + return ( +
+ {/* ── Header: repo name + GitHub link ────────────────────────── */} +
+
+

+ {shortName} +

+

+ {health.repo} +

+
+ + +
+ + {/* ── Gauge + Grade card ──────────────────────────────────────── */} +
+ {/* Gauge */} +
+ +
+ + {/* Grade card */} +
+ + + {label} + + + Score: {health.score}/100 + + + {health.grade} + +
+
+ + {/* ── Radar chart ─────────────────────────────────────────────── */} +
+

+ Dimension Overview +

+

+ Each axis is normalised to 0–100 for visual balance. +

+ +
+ + {/* ── Score breakdown ─────────────────────────────────────────── */} +
+ +
+ + {/* ── Recommendations ─────────────────────────────────────────── */} +
+ +
+
+ ); +}); + +// --------------------------------------------------------------------------- +// Skeleton +// --------------------------------------------------------------------------- + +function CardSkeleton() { + return ( +
+
+
+
+
+
+
+
+
+
+
+ ); +} + +// --------------------------------------------------------------------------- +// Main explorer +// --------------------------------------------------------------------------- + +export default function RepoHealthExplorer() { + const { selectedAccount } = useAccount(); + const [healthScores, setHealthScores] = useState([]); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + const [days, setDays] = useState(30); + const [selectedRepo, setSelectedRepo] = useState(null); + + const fetchScores = useCallback(() => { + setLoading(true); + setError(null); + + const accountParam = + selectedAccount != null + ? `&accountId=${encodeURIComponent(selectedAccount)}` + : ""; + + fetch(`/api/metrics/repo-health?days=${days}${accountParam}`) + .then((r) => r.json()) + .then((d: { repos?: RepoHealthScore[]; error?: string }) => { + if (d.error) throw new Error(d.error); + const repos = (d.repos ?? []).sort((a, b) => b.score - a.score); + setHealthScores(repos); + // Auto-select the top-scoring repo on first load + if (!selectedRepo && repos.length > 0) { + setSelectedRepo(repos[0].repo); + } + }) + .catch((err: unknown) => { + setError( + err instanceof Error && err.message !== "GitHub API error" + ? err.message + : "Unable to load repository health data. Please try again." + ); + }) + .finally(() => setLoading(false)); + // eslint-disable-next-line react-hooks/exhaustive-deps + }, [days, selectedAccount]); + + // Persist selected days range across sessions + useEffect(() => { + const saved = localStorage.getItem("devtrack_health_range"); + if (saved && ["7", "30", "90"].includes(saved)) { + setDays(Number(saved)); + } + }, []); + + useEffect(() => { + localStorage.setItem("devtrack_health_range", String(days)); + }, [days]); + + useEffect(() => { + fetchScores(); + }, [fetchScores]); + + const selectedHealth = useMemo( + () => healthScores.find((h) => h.repo === selectedRepo) ?? null, + [healthScores, selectedRepo] + ); + + return ( +
+ {/* ── Page header ─────────────────────────────────────────────── */} +
+
+ +
+ +
+ + + + +
+
+ + {/* ── Error state ─────────────────────────────────────────────── */} + {error && ( +
+

{error}

+ +
+ )} + + {/* ── Two-column layout ────────────────────────────────────────── */} +
+ {/* ── Left panel: repo list ──────────────────────────────────── */} + + + {/* ── Right panel: detail view ───────────────────────────────── */} +
+ {loading ? ( +
+
+
+
+
+
+
+
+
+
+ ) : selectedHealth ? ( + + ) : ( +
+ +

+ Select a repository +

+

+ Choose a repository from the list on the left to see its full + health breakdown and recommendations. +

+
+ )} +
+
+
+ ); +} diff --git a/src/components/repo-health/RepoHealthGauge.tsx b/src/components/repo-health/RepoHealthGauge.tsx new file mode 100644 index 00000000..54c016ac --- /dev/null +++ b/src/components/repo-health/RepoHealthGauge.tsx @@ -0,0 +1,117 @@ +"use client"; + +import { memo } from "react"; + +interface Props { + score: number; + grade: "green" | "yellow" | "red"; +} + +const GRADE_COLOR: Record = { + green: "var(--accent)", + yellow: "#ca8a04", + red: "var(--destructive)", +}; + +/** + * Semi-circle SVG gauge that displays the 0-100 composite health score. + * + * The filled arc grows from left (0) to right (100) along the top of the + * semi-circle. Implemented with an SVG path so it works without any + * charting library dependency and remains accessible to screen readers. + */ +function RepoHealthGauge({ score, grade }: Props) { + // Geometry constants + const CX = 100; + const CY = 95; + const R = 72; + const STROKE = 14; + + const pct = Math.max(0, Math.min(1, score / 100)); + + // Standard-math polar → SVG cartesian (SVG y-axis is flipped) + const polar = (deg: number) => ({ + x: CX + R * Math.cos((deg * Math.PI) / 180), + y: CY - R * Math.sin((deg * Math.PI) / 180), + }); + + // Track arc: full 180° semi-circle from left (180°) to right (0°) + const tl = polar(180); + const tr = polar(0); + const trackPath = `M ${tl.x} ${tl.y} A ${R} ${R} 0 1 0 ${tr.x} ${tr.y}`; + + // Fill arc: from left (180°) to (180° − pct×180°) + let fillPath: string | null = null; + if (pct > 0) { + if (pct >= 1) { + fillPath = trackPath; + } else { + const endAngle = 180 - pct * 180; + const fe = polar(endAngle); + // Arc spans pct×180° which is always < 180°, so large-arc = 0 + fillPath = `M ${tl.x} ${tl.y} A ${R} ${R} 0 0 0 ${fe.x.toFixed(2)} ${fe.y.toFixed(2)}`; + } + } + + const color = GRADE_COLOR[grade] ?? GRADE_COLOR.red; + + return ( +
+ + {/* Background track */} + + + {/* Filled arc (score portion) */} + {fillPath && ( + + )} + + {/* Score text */} + + + {/* "/ 100" label */} + + +
+ ); +} + +export default memo(RepoHealthGauge); diff --git a/src/components/repo-health/RepoHealthInsights.tsx b/src/components/repo-health/RepoHealthInsights.tsx new file mode 100644 index 00000000..29f6d3de --- /dev/null +++ b/src/components/repo-health/RepoHealthInsights.tsx @@ -0,0 +1,106 @@ +"use client"; + +import { memo } from "react"; +import type { HealthInsight } from "@/lib/repo-health-insights"; + +interface Props { + insights: HealthInsight[]; +} + +const SEVERITY_STYLES: Record< + HealthInsight["severity"], + { border: string; bg: string; text: string; icon: string } +> = { + warning: { + border: "border-[var(--destructive)]/30", + bg: "bg-[var(--destructive)]/8", + text: "text-[var(--destructive)]", + icon: "⚠", + }, + info: { + border: "border-[var(--accent)]/30", + bg: "bg-[var(--accent)]/8", + text: "text-[var(--accent)]", + icon: "ℹ", + }, + success: { + border: "border-[var(--success,#16a34a)]/30", + bg: "bg-[var(--success,#16a34a)]/8", + text: "text-[var(--success,#16a34a)]", + icon: "✓", + }, +}; + +/** + * Rule-based recommendations panel. + * + * Each `HealthInsight` is rendered as a bordered card colour-coded by + * severity. The insights themselves are produced by `generateInsights()` in + * `@/lib/repo-health-insights` and are fully data-driven. + */ +function RepoHealthInsights({ insights }: Props) { + if (insights.length === 0) { + return ( +
+

+ Recommendations +

+

+ No recommendations at this time — all metrics look good. +

+
+ ); + } + + const warnings = insights.filter((i) => i.severity === "warning"); + const infos = insights.filter((i) => i.severity === "info"); + const successes = insights.filter((i) => i.severity === "success"); + const ordered = [...warnings, ...infos, ...successes]; + + return ( +
+

+ Recommendations + {warnings.length > 0 && ( + + {warnings.length} action{warnings.length !== 1 ? "s" : ""} + + )} +

+ +
    + {ordered.map((insight) => { + const styles = SEVERITY_STYLES[insight.severity]; + return ( +
  • +
    + +
    +

    + {insight.title} +

    +

    + {insight.description} +

    + + {insight.metric} + +
    +
    +
    • + ); + })} +
+
+ ); +} + +export default memo(RepoHealthInsights); diff --git a/src/components/repo-health/RepoHealthRadar.tsx b/src/components/repo-health/RepoHealthRadar.tsx new file mode 100644 index 00000000..873d88a2 --- /dev/null +++ b/src/components/repo-health/RepoHealthRadar.tsx @@ -0,0 +1,61 @@ +"use client"; + +import { memo } from "react"; +import { + Radar, + RadarChart, + PolarGrid, + PolarAngleAxis, + ResponsiveContainer, +} from "recharts"; +import type { RadarDatum } from "@/lib/repo-health-insights"; + +interface Props { + data: RadarDatum[]; + grade: "green" | "yellow" | "red"; +} + +const GRADE_COLOR: Record = { + green: "var(--accent)", + yellow: "#ca8a04", + red: "var(--destructive)", +}; + +/** + * Radar chart visualising the five health sub-scores, each normalised to + * 0-100 so the axes are visually balanced regardless of their differing + * maximum weights (25 / 25 / 20 / 15 / 15 pts). + */ +function RepoHealthRadar({ data, grade }: Props) { + const color = GRADE_COLOR[grade] ?? GRADE_COLOR.red; + + return ( + + + + + + + + ); +} + +export default memo(RepoHealthRadar); diff --git a/src/lib/repo-health-insights.ts b/src/lib/repo-health-insights.ts new file mode 100644 index 00000000..acfba992 --- /dev/null +++ b/src/lib/repo-health-insights.ts @@ -0,0 +1,345 @@ +/** + * Pure helper functions for the Repository Health Explorer. + * + * All logic is data-driven: no repository names are referenced and no + * thresholds are hard-coded for specific repos. The same functions are used + * for both the UI layer and the test suite. + */ + +import type { RepoHealthSignals } from "@/types/repo-health"; +import { + scoreCommitFrequency, + scorePrMergeRate, + scoreAvgPrOpenTimeHours, + scoreOpenIssuesCount, + scoreDaysSinceLastCommit, +} from "@/lib/repo-health"; + +// --------------------------------------------------------------------------- +// Grade letters +// --------------------------------------------------------------------------- + +/** + * Converts the 0-100 composite health score to a letter grade with modifiers. + * The three-tier system (green / yellow / red) from `gradeForScore` is + * preserved; this function adds finer granularity for display purposes only. + */ +export function gradeLetter(score: number): string { + if (score >= 90) return "A+"; + if (score >= 80) return "A"; + if (score >= 70) return "A−"; + if (score >= 60) return "B+"; + if (score >= 50) return "B"; + if (score >= 40) return "B−"; + if (score >= 30) return "C+"; + if (score >= 20) return "C"; + return "D"; +} + +/** Human-readable tier label for a health grade. */ +export function gradeLabel(grade: "green" | "yellow" | "red"): string { + switch (grade) { + case "green": + return "Healthy"; + case "yellow": + return "Needs Attention"; + case "red": + return "At Risk"; + } +} + +// --------------------------------------------------------------------------- +// Radar chart data +// --------------------------------------------------------------------------- + +export interface RadarDatum { + /** Short axis label displayed on the chart. */ + metric: string; + /** Normalised 0-100 value (each sub-score divided by its max weight). */ + value: number; + /** Always 100 — used by recharts to draw the reference polygon. */ + fullMark: number; +} + +/** + * Normalises each sub-score to a 0-100 scale so all five axes are + * comparable in the radar chart regardless of their different max weights. + */ +export function buildRadarData(signals: RepoHealthSignals): RadarDatum[] { + return [ + { + metric: "Commits", + value: Math.round((scoreCommitFrequency(signals.commitFrequency) / 25) * 100), + fullMark: 100, + }, + { + metric: "PR Rate", + value: Math.round((scorePrMergeRate(signals.prMergeRate) / 25) * 100), + fullMark: 100, + }, + { + metric: "PR Speed", + value: Math.round((scoreAvgPrOpenTimeHours(signals.avgPrOpenTimeHours) / 20) * 100), + fullMark: 100, + }, + { + metric: "Issues", + value: Math.round((scoreOpenIssuesCount(signals.openIssuesCount) / 15) * 100), + fullMark: 100, + }, + { + metric: "Activity", + value: Math.round((scoreDaysSinceLastCommit(signals.daysSinceLastCommit) / 15) * 100), + fullMark: 100, + }, + ]; +} + +// --------------------------------------------------------------------------- +// Score breakdown table +// --------------------------------------------------------------------------- + +export interface BreakdownRow { + /** Metric display name. */ + label: string; + /** Formatted raw signal value (e.g. "12 commits", "65%"). */ + rawValue: string; + /** Points earned for this dimension. */ + earned: number; + /** Maximum possible points for this dimension. */ + maxScore: number; + /** Target description shown as a tooltip / helper text. */ + tip: string; + /** Weight contribution as a percentage of total score. */ + weightPct: number; +} + +/** + * Builds the per-dimension score breakdown displayed in the breakdown table. + * The earned scores are calculated with the same functions used by + * `computeHealthScore` so the numbers are always consistent. + */ +export function buildBreakdown(signals: RepoHealthSignals): BreakdownRow[] { + return [ + { + label: "Commit Frequency", + rawValue: + signals.commitFrequency === 1 + ? "1 commit" + : `${signals.commitFrequency} commits`, + earned: Math.round(scoreCommitFrequency(signals.commitFrequency)), + maxScore: 25, + tip: "Target: 10 or more commits in the analysis window", + weightPct: 25, + }, + { + label: "PR Merge Rate", + rawValue: `${Math.round(signals.prMergeRate * 100)}%`, + earned: Math.round(scorePrMergeRate(signals.prMergeRate)), + maxScore: 25, + tip: "Target: 100% of opened PRs merged", + weightPct: 25, + }, + { + label: "PR Turnaround", + rawValue: + signals.avgPrOpenTimeHours === 0 + ? "No PRs" + : `${Math.round(signals.avgPrOpenTimeHours)}h avg`, + earned: Math.round(scoreAvgPrOpenTimeHours(signals.avgPrOpenTimeHours)), + maxScore: 20, + tip: "Target: under 24 hours average", + weightPct: 20, + }, + { + label: "Open Issues", + rawValue: + signals.openIssuesCount === 1 + ? "1 open issue" + : `${signals.openIssuesCount} open issues`, + earned: Math.round(scoreOpenIssuesCount(signals.openIssuesCount)), + maxScore: 15, + tip: "Target: 0 open issues", + weightPct: 15, + }, + { + label: "Recent Activity", + rawValue: + signals.daysSinceLastCommit >= 9999 + ? "Unknown" + : signals.daysSinceLastCommit === 0 + ? "Today" + : `${signals.daysSinceLastCommit}d ago`, + earned: Math.round(scoreDaysSinceLastCommit(signals.daysSinceLastCommit)), + maxScore: 15, + tip: "Target: commit within the last 7 days", + weightPct: 15, + }, + ]; +} + +// --------------------------------------------------------------------------- +// Recommendations engine +// --------------------------------------------------------------------------- + +export interface HealthInsight { + id: string; + severity: "warning" | "success" | "info"; + title: string; + description: string; + /** Which metric produced this insight. */ + metric: string; +} + +/** + * Rule-based recommendations engine. + * + * Each rule checks a single signal against a threshold and produces an + * insight with a severity level. Rules are data-driven: all thresholds come + * from the health-scoring functions in `@/lib/repo-health`, ensuring the + * insights are always consistent with the numeric scores. + */ +export function generateInsights(signals: RepoHealthSignals): HealthInsight[] { + const insights: HealthInsight[] = []; + + // ── Commit frequency ─────────────────────────────────────────────────── + if (signals.commitFrequency === 0) { + insights.push({ + id: "no-commits", + severity: "warning", + title: "No recent commits", + description: + "No commits were detected in the analysis window. Regular commits keep the repository active and the score healthy.", + metric: "Commit Frequency", + }); + } else if (signals.commitFrequency < 3) { + insights.push({ + id: "low-commits", + severity: "warning", + title: "Low commit frequency", + description: `Only ${signals.commitFrequency} commit(s) in the analysis window. Aim for 10 or more per period to reach a full commit score.`, + metric: "Commit Frequency", + }); + } else if (signals.commitFrequency >= 10) { + insights.push({ + id: "good-commits", + severity: "success", + title: "Strong commit activity", + description: `${signals.commitFrequency} commits in the analysis window — at or above the healthy threshold of 10.`, + metric: "Commit Frequency", + }); + } + + // ── PR merge rate ────────────────────────────────────────────────────── + if (signals.prMergeRate > 0 && signals.prMergeRate < 0.5) { + insights.push({ + id: "low-merge-rate", + severity: "warning", + title: "Low PR merge rate", + description: `Only ${Math.round(signals.prMergeRate * 100)}% of opened PRs were merged. Review and close stale pull requests to improve this signal.`, + metric: "PR Merge Rate", + }); + } else if (signals.prMergeRate >= 0.8) { + insights.push({ + id: "good-merge-rate", + severity: "success", + title: "Excellent PR merge rate", + description: `${Math.round(signals.prMergeRate * 100)}% of opened PRs were merged — healthy indicator of active code review.`, + metric: "PR Merge Rate", + }); + } + + // ── PR turnaround ────────────────────────────────────────────────────── + if (signals.avgPrOpenTimeHours > 168) { + insights.push({ + id: "slow-prs", + severity: "warning", + title: "Long PR review cycle", + description: `Average PR open time is ${Math.round(signals.avgPrOpenTimeHours / 24)} day(s). Faster reviews reduce integration risk and improve velocity.`, + metric: "PR Turnaround", + }); + } else if (signals.avgPrOpenTimeHours > 72) { + insights.push({ + id: "moderate-prs", + severity: "info", + title: "PR review time above average", + description: `Average PR open time is ${Math.round(signals.avgPrOpenTimeHours)}h. Target under 48 hours for a healthy review cycle.`, + metric: "PR Turnaround", + }); + } else if (signals.avgPrOpenTimeHours > 0 && signals.avgPrOpenTimeHours <= 24) { + insights.push({ + id: "fast-prs", + severity: "success", + title: "Fast PR turnaround", + description: + "PRs are reviewed and closed in under 24 hours on average — excellent review velocity.", + metric: "PR Turnaround", + }); + } + + // ── Open issues ──────────────────────────────────────────────────────── + if (signals.openIssuesCount >= 20) { + insights.push({ + id: "high-issues", + severity: "warning", + title: "High open issue count", + description: `${signals.openIssuesCount} open issues detected. Triage and close resolved or duplicate issues to reduce backlog pressure.`, + metric: "Open Issues", + }); + } else if (signals.openIssuesCount > 10) { + insights.push({ + id: "moderate-issues", + severity: "info", + title: "Issue backlog growing", + description: `${signals.openIssuesCount} open issues. Consider scheduling a triage session for older tickets.`, + metric: "Open Issues", + }); + } else if (signals.openIssuesCount === 0) { + insights.push({ + id: "no-issues", + severity: "success", + title: "No open issues", + description: + "Issue backlog is clear — all reported problems have been addressed or closed.", + metric: "Open Issues", + }); + } + + // ── Recency ──────────────────────────────────────────────────────────── + if (signals.daysSinceLastCommit >= 9999) { + insights.push({ + id: "no-commit-data", + severity: "info", + title: "Commit history unavailable", + description: + "Could not determine the date of the last commit. Verify repository access permissions.", + metric: "Recent Activity", + }); + } else if (signals.daysSinceLastCommit >= 30) { + insights.push({ + id: "stale-repo", + severity: "warning", + title: "Repository may be stale", + description: `The last commit was ${signals.daysSinceLastCommit} days ago. Push an update if this project is still active.`, + metric: "Recent Activity", + }); + } else if (signals.daysSinceLastCommit > 14) { + insights.push({ + id: "low-activity", + severity: "info", + title: "Reduced recent activity", + description: `Last commit was ${signals.daysSinceLastCommit} days ago. Consistent activity keeps the recency score high.`, + metric: "Recent Activity", + }); + } else if (signals.daysSinceLastCommit <= 3) { + insights.push({ + id: "active-repo", + severity: "success", + title: "Actively maintained", + description: `Last commit was ${signals.daysSinceLastCommit <= 0 ? "today" : `${signals.daysSinceLastCommit} day(s) ago`} — excellent recency signal.`, + metric: "Recent Activity", + }); + } + + return insights; +} diff --git a/test/repo-health-explorer.test.ts b/test/repo-health-explorer.test.ts new file mode 100644 index 00000000..e6ba0e4f --- /dev/null +++ b/test/repo-health-explorer.test.ts @@ -0,0 +1,543 @@ +/** + * Tests for the Repository Health Explorer + * + * Covers: + * - Existing health scoring functions (regression — values must remain unchanged) + * - gradeLetter: full range including edge cases + * - gradeLabel: all three tiers + * - buildRadarData: normalisation, structure, boundary values + * - buildBreakdown: earned scores, maxScore, rawValue formatting + * - generateInsights: all five signal dimensions × multiple thresholds + */ + +import { describe, expect, it } from "vitest"; + +import { + computeHealthScore, + gradeForScore, + scoreCommitFrequency, + scorePrMergeRate, + scoreAvgPrOpenTimeHours, + scoreOpenIssuesCount, + scoreDaysSinceLastCommit, +} from "@/lib/repo-health"; + +import { + buildBreakdown, + buildRadarData, + generateInsights, + gradeLetter, + gradeLabel, +} from "@/lib/repo-health-insights"; + +import type { RepoHealthSignals } from "@/types/repo-health"; + +// --------------------------------------------------------------------------- +// Helper fixtures +// --------------------------------------------------------------------------- + +const perfectSignals: RepoHealthSignals = { + commitFrequency: 10, + prMergeRate: 1, + avgPrOpenTimeHours: 0, + openIssuesCount: 0, + daysSinceLastCommit: 0, +}; + +const worstSignals: RepoHealthSignals = { + commitFrequency: 0, + prMergeRate: 0, + avgPrOpenTimeHours: 9999, + openIssuesCount: 999, + daysSinceLastCommit: 9999, +}; + +const midSignals: RepoHealthSignals = { + commitFrequency: 5, + prMergeRate: 0.6, + avgPrOpenTimeHours: 48, + openIssuesCount: 8, + daysSinceLastCommit: 10, +}; + +// --------------------------------------------------------------------------- +// Regression: existing health scoring functions +// (These tests guard against accidental changes to the scoring logic.) +// --------------------------------------------------------------------------- + +describe("scoreCommitFrequency (regression)", () => { + it("returns 25 for 10+ commits", () => { + expect(scoreCommitFrequency(10)).toBe(25); + expect(scoreCommitFrequency(100)).toBe(25); + }); + + it("returns 0 for 0 commits", () => { + expect(scoreCommitFrequency(0)).toBe(0); + }); + + it("returns 12.5 for 5 commits (50% of max)", () => { + expect(scoreCommitFrequency(5)).toBe(12.5); + }); +}); + +describe("scorePrMergeRate (regression)", () => { + it("returns 25 for rate 1.0", () => { + expect(scorePrMergeRate(1)).toBe(25); + }); + + it("returns 0 for rate 0", () => { + expect(scorePrMergeRate(0)).toBe(0); + }); + + it("returns 12.5 for rate 0.5", () => { + expect(scorePrMergeRate(0.5)).toBe(12.5); + }); + + it("clamps to 25 for rate > 1", () => { + expect(scorePrMergeRate(2)).toBe(25); + }); +}); + +describe("scoreAvgPrOpenTimeHours (regression)", () => { + it("returns 20 for 0 hours", () => { + expect(scoreAvgPrOpenTimeHours(0)).toBe(20); + }); + + it("returns 20 for exactly 24 hours", () => { + expect(scoreAvgPrOpenTimeHours(24)).toBe(20); + }); + + it("returns 0 for 168 hours or more", () => { + expect(scoreAvgPrOpenTimeHours(168)).toBe(0); + expect(scoreAvgPrOpenTimeHours(9999)).toBe(0); + }); + + it("scales linearly between 24 and 168 hours", () => { + const score = scoreAvgPrOpenTimeHours(96); + expect(score).toBeGreaterThan(0); + expect(score).toBeLessThan(20); + }); +}); + +describe("scoreOpenIssuesCount (regression)", () => { + it("returns 15 for 0 issues", () => { + expect(scoreOpenIssuesCount(0)).toBe(15); + }); + + it("returns 0 for 20+ issues", () => { + expect(scoreOpenIssuesCount(20)).toBe(0); + expect(scoreOpenIssuesCount(100)).toBe(0); + }); + + it("scales linearly between 0 and 20 issues", () => { + const score = scoreOpenIssuesCount(10); + expect(score).toBeGreaterThan(0); + expect(score).toBeLessThan(15); + }); +}); + +describe("scoreDaysSinceLastCommit (regression)", () => { + it("returns 15 for 0 days", () => { + expect(scoreDaysSinceLastCommit(0)).toBe(15); + }); + + it("returns 15 for exactly 7 days", () => { + expect(scoreDaysSinceLastCommit(7)).toBe(15); + }); + + it("returns 0 for 30+ days", () => { + expect(scoreDaysSinceLastCommit(30)).toBe(0); + expect(scoreDaysSinceLastCommit(9999)).toBe(0); + }); + + it("scales between 7 and 30 days", () => { + const score = scoreDaysSinceLastCommit(14); + expect(score).toBeGreaterThan(0); + expect(score).toBeLessThan(15); + }); +}); + +describe("gradeForScore (regression)", () => { + it("returns green for scores 70+", () => { + expect(gradeForScore(70)).toBe("green"); + expect(gradeForScore(100)).toBe("green"); + }); + + it("returns yellow for scores 40-69", () => { + expect(gradeForScore(40)).toBe("yellow"); + expect(gradeForScore(69)).toBe("yellow"); + }); + + it("returns red for scores below 40", () => { + expect(gradeForScore(0)).toBe("red"); + expect(gradeForScore(39)).toBe("red"); + }); +}); + +describe("computeHealthScore (regression)", () => { + it("returns score 100 for perfect signals", () => { + const result = computeHealthScore("owner/repo", perfectSignals); + expect(result.score).toBe(100); + expect(result.grade).toBe("green"); + }); + + it("returns score 0 for worst-case signals", () => { + const result = computeHealthScore("owner/repo", worstSignals); + expect(result.score).toBe(0); + expect(result.grade).toBe("red"); + }); + + it("includes the repo name in the result", () => { + const result = computeHealthScore("my-org/my-repo", perfectSignals); + expect(result.repo).toBe("my-org/my-repo"); + }); + + it("includes the original signals in the result", () => { + const result = computeHealthScore("owner/repo", midSignals); + expect(result.signals).toEqual(midSignals); + }); +}); + +// --------------------------------------------------------------------------- +// gradeLetter +// --------------------------------------------------------------------------- + +describe("gradeLetter", () => { + it("returns A+ for scores 90-100", () => { + expect(gradeLetter(90)).toBe("A+"); + expect(gradeLetter(100)).toBe("A+"); + }); + + it("returns A for scores 80-89", () => { + expect(gradeLetter(80)).toBe("A"); + expect(gradeLetter(89)).toBe("A"); + }); + + it("returns A− for scores 70-79", () => { + expect(gradeLetter(70)).toBe("A−"); + expect(gradeLetter(79)).toBe("A−"); + }); + + it("returns B+ for scores 60-69", () => { + expect(gradeLetter(60)).toBe("B+"); + expect(gradeLetter(69)).toBe("B+"); + }); + + it("returns B for scores 50-59", () => { + expect(gradeLetter(50)).toBe("B"); + expect(gradeLetter(59)).toBe("B"); + }); + + it("returns B− for scores 40-49", () => { + expect(gradeLetter(40)).toBe("B−"); + expect(gradeLetter(49)).toBe("B−"); + }); + + it("returns C+ for scores 30-39", () => { + expect(gradeLetter(30)).toBe("C+"); + expect(gradeLetter(39)).toBe("C+"); + }); + + it("returns C for scores 20-29", () => { + expect(gradeLetter(20)).toBe("C"); + expect(gradeLetter(29)).toBe("C"); + }); + + it("returns D for scores below 20", () => { + expect(gradeLetter(0)).toBe("D"); + expect(gradeLetter(19)).toBe("D"); + }); +}); + +// --------------------------------------------------------------------------- +// gradeLabel +// --------------------------------------------------------------------------- + +describe("gradeLabel", () => { + it("returns Healthy for green", () => { + expect(gradeLabel("green")).toBe("Healthy"); + }); + + it("returns Needs Attention for yellow", () => { + expect(gradeLabel("yellow")).toBe("Needs Attention"); + }); + + it("returns At Risk for red", () => { + expect(gradeLabel("red")).toBe("At Risk"); + }); +}); + +// --------------------------------------------------------------------------- +// buildRadarData +// --------------------------------------------------------------------------- + +describe("buildRadarData", () => { + it("returns exactly 5 entries", () => { + expect(buildRadarData(perfectSignals)).toHaveLength(5); + }); + + it("every entry has fullMark = 100", () => { + for (const datum of buildRadarData(midSignals)) { + expect(datum.fullMark).toBe(100); + } + }); + + it("all entries are 100 for perfect signals", () => { + const data = buildRadarData(perfectSignals); + for (const datum of data) { + expect(datum.value).toBe(100); + } + }); + + it("all entries are 0 for worst-case signals", () => { + const data = buildRadarData(worstSignals); + for (const datum of data) { + expect(datum.value).toBe(0); + } + }); + + it("values are in the range 0-100", () => { + const data = buildRadarData(midSignals); + for (const datum of data) { + expect(datum.value).toBeGreaterThanOrEqual(0); + expect(datum.value).toBeLessThanOrEqual(100); + } + }); + + it("has the expected metric labels in order", () => { + const labels = buildRadarData(perfectSignals).map((d) => d.metric); + expect(labels).toEqual(["Commits", "PR Rate", "PR Speed", "Issues", "Activity"]); + }); + + it("Commits entry is proportional to scoreCommitFrequency", () => { + const signals: RepoHealthSignals = { ...perfectSignals, commitFrequency: 5 }; + const data = buildRadarData(signals); + const commits = data.find((d) => d.metric === "Commits")!; + // 5 commits = 12.5/25 * 100 = 50 + expect(commits.value).toBe(50); + }); +}); + +// --------------------------------------------------------------------------- +// buildBreakdown +// --------------------------------------------------------------------------- + +describe("buildBreakdown", () => { + it("returns exactly 5 rows", () => { + expect(buildBreakdown(perfectSignals)).toHaveLength(5); + }); + + it("weights sum to 100", () => { + const total = buildBreakdown(perfectSignals).reduce( + (sum, row) => sum + row.weightPct, + 0 + ); + expect(total).toBe(100); + }); + + it("maxScores sum to 100", () => { + const total = buildBreakdown(perfectSignals).reduce( + (sum, row) => sum + row.maxScore, + 0 + ); + expect(total).toBe(100); + }); + + it("earned scores match the scoring functions for perfect signals", () => { + const rows = buildBreakdown(perfectSignals); + const commitRow = rows.find((r) => r.label === "Commit Frequency")!; + const prRateRow = rows.find((r) => r.label === "PR Merge Rate")!; + + expect(commitRow.earned).toBe(Math.round(scoreCommitFrequency(perfectSignals.commitFrequency))); + expect(prRateRow.earned).toBe(Math.round(scorePrMergeRate(perfectSignals.prMergeRate))); + }); + + it("earned is 0 for worst-case signals", () => { + const rows = buildBreakdown(worstSignals); + for (const row of rows) { + expect(row.earned).toBe(0); + } + }); + + it("formats zero PR open time as No PRs", () => { + const rows = buildBreakdown({ ...perfectSignals, avgPrOpenTimeHours: 0 }); + const prRow = rows.find((r) => r.label === "PR Turnaround")!; + expect(prRow.rawValue).toBe("No PRs"); + }); + + it("formats daysSinceLastCommit >= 9999 as Unknown", () => { + const rows = buildBreakdown(worstSignals); + const actRow = rows.find((r) => r.label === "Recent Activity")!; + expect(actRow.rawValue).toBe("Unknown"); + }); + + it("formats 0 daysSinceLastCommit as Today", () => { + const rows = buildBreakdown({ ...perfectSignals, daysSinceLastCommit: 0 }); + const actRow = rows.find((r) => r.label === "Recent Activity")!; + expect(actRow.rawValue).toBe("Today"); + }); + + it("formats 1 commit as singular", () => { + const rows = buildBreakdown({ ...perfectSignals, commitFrequency: 1 }); + const row = rows.find((r) => r.label === "Commit Frequency")!; + expect(row.rawValue).toBe("1 commit"); + }); +}); + +// --------------------------------------------------------------------------- +// generateInsights +// --------------------------------------------------------------------------- + +describe("generateInsights — commit frequency", () => { + it("emits a warning for 0 commits", () => { + const insights = generateInsights({ ...perfectSignals, commitFrequency: 0 }); + const i = insights.find((x) => x.id === "no-commits"); + expect(i).toBeDefined(); + expect(i!.severity).toBe("warning"); + expect(i!.metric).toBe("Commit Frequency"); + }); + + it("emits a warning for < 3 commits", () => { + const insights = generateInsights({ ...perfectSignals, commitFrequency: 2 }); + expect(insights.find((x) => x.id === "low-commits")).toBeDefined(); + }); + + it("emits a success for 10+ commits", () => { + const insights = generateInsights({ ...perfectSignals, commitFrequency: 15 }); + expect(insights.find((x) => x.id === "good-commits")).toBeDefined(); + }); + + it("emits no commit insight for 3–9 commits", () => { + const insights = generateInsights({ ...perfectSignals, commitFrequency: 6 }); + const ids = insights.map((i) => i.id); + expect(ids).not.toContain("no-commits"); + expect(ids).not.toContain("low-commits"); + expect(ids).not.toContain("good-commits"); + }); +}); + +describe("generateInsights — PR merge rate", () => { + it("emits a warning for rate > 0 and < 0.5", () => { + const insights = generateInsights({ ...perfectSignals, prMergeRate: 0.3 }); + expect(insights.find((x) => x.id === "low-merge-rate")).toBeDefined(); + }); + + it("emits a success for rate >= 0.8", () => { + const insights = generateInsights({ ...perfectSignals, prMergeRate: 0.9 }); + expect(insights.find((x) => x.id === "good-merge-rate")).toBeDefined(); + }); + + it("emits no PR rate insight for rate 0 (no PRs opened)", () => { + const insights = generateInsights({ ...perfectSignals, prMergeRate: 0 }); + const ids = insights.map((i) => i.id); + expect(ids).not.toContain("low-merge-rate"); + expect(ids).not.toContain("good-merge-rate"); + }); +}); + +describe("generateInsights — PR turnaround", () => { + it("emits a warning for > 168 hours", () => { + const insights = generateInsights({ ...perfectSignals, avgPrOpenTimeHours: 200 }); + expect(insights.find((x) => x.id === "slow-prs")).toBeDefined(); + }); + + it("emits an info for 72–168 hours", () => { + const insights = generateInsights({ ...perfectSignals, avgPrOpenTimeHours: 100 }); + expect(insights.find((x) => x.id === "moderate-prs")).toBeDefined(); + }); + + it("emits a success for <= 24 hours (and > 0)", () => { + const insights = generateInsights({ ...perfectSignals, avgPrOpenTimeHours: 12 }); + expect(insights.find((x) => x.id === "fast-prs")).toBeDefined(); + }); + + it("emits no PR speed insight for 0 hours", () => { + const insights = generateInsights({ ...perfectSignals, avgPrOpenTimeHours: 0 }); + const ids = insights.map((i) => i.id); + expect(ids).not.toContain("fast-prs"); + expect(ids).not.toContain("slow-prs"); + expect(ids).not.toContain("moderate-prs"); + }); +}); + +describe("generateInsights — open issues", () => { + it("emits a warning for >= 20 issues", () => { + const insights = generateInsights({ ...perfectSignals, openIssuesCount: 25 }); + expect(insights.find((x) => x.id === "high-issues")).toBeDefined(); + }); + + it("emits an info for 11–19 issues", () => { + const insights = generateInsights({ ...perfectSignals, openIssuesCount: 15 }); + expect(insights.find((x) => x.id === "moderate-issues")).toBeDefined(); + }); + + it("emits a success for 0 issues", () => { + const insights = generateInsights({ ...perfectSignals, openIssuesCount: 0 }); + expect(insights.find((x) => x.id === "no-issues")).toBeDefined(); + }); + + it("emits no issue insight for 1–10 issues", () => { + const insights = generateInsights({ ...perfectSignals, openIssuesCount: 5 }); + const ids = insights.map((i) => i.id); + expect(ids).not.toContain("no-issues"); + expect(ids).not.toContain("high-issues"); + expect(ids).not.toContain("moderate-issues"); + }); +}); + +describe("generateInsights — recent activity", () => { + it("emits an info for daysSinceLastCommit >= 9999", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 9999 }); + expect(insights.find((x) => x.id === "no-commit-data")).toBeDefined(); + }); + + it("emits a warning for >= 30 days", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 45 }); + expect(insights.find((x) => x.id === "stale-repo")).toBeDefined(); + }); + + it("emits an info for 15–29 days", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 20 }); + expect(insights.find((x) => x.id === "low-activity")).toBeDefined(); + }); + + it("emits a success for <= 3 days", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 2 }); + expect(insights.find((x) => x.id === "active-repo")).toBeDefined(); + }); + + it("emits a success for 0 days (today)", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 0 }); + const i = insights.find((x) => x.id === "active-repo"); + expect(i).toBeDefined(); + expect(i!.description).toContain("today"); + }); + + it("emits no recency insight for 4–14 days (neutral zone)", () => { + const insights = generateInsights({ ...perfectSignals, daysSinceLastCommit: 9 }); + const ids = insights.map((i) => i.id); + expect(ids).not.toContain("active-repo"); + expect(ids).not.toContain("low-activity"); + expect(ids).not.toContain("stale-repo"); + }); +}); + +describe("generateInsights — severity ordering helpers", () => { + it("all insights have one of the three valid severity values", () => { + const insights = generateInsights(midSignals); + const valid = new Set(["warning", "info", "success"]); + for (const i of insights) { + expect(valid).toContain(i.severity); + } + }); + + it("all insights have non-empty id, title, description and metric", () => { + const insights = generateInsights(midSignals); + for (const i of insights) { + expect(i.id.length).toBeGreaterThan(0); + expect(i.title.length).toBeGreaterThan(0); + expect(i.description.length).toBeGreaterThan(0); + expect(i.metric.length).toBeGreaterThan(0); + } + }); +});