@git-snitch/renderer 0.0.3

package/src/overview.tsx

@@ -0,0 +1,253 @@
+import { Card, CardContent, CardHeader, CardTitle } from "@git-snitch/ui/components/card";
+
+import type { CommitRecord, GitHubRepoMeta, RepoReportData, ReportData } from "@git-snitch/core";
+
+import { CommitActivityChart, deriveCommitActivityData } from "./charts.js";
+import { EmptyState } from "./empty-state.js";
+import { StatsGrid } from "./layout.js";
+
+type StreakSummary =
+  | {
+      readonly status: "ready";
+      readonly current: number;
+      readonly longest: number;
+      readonly anchorDate: string;
+    }
+  | { readonly status: "empty" }
+  | { readonly status: "insufficient-dates" };
+
+function parseCommitDay(commit: CommitRecord) {
+  const timestamp = Date.parse(commit.authoredAt);
+
+  if (Number.isNaN(timestamp)) {
+    return undefined;
+  }
+
+  return new Date(timestamp).toISOString().slice(0, 10);
+}
+
+function nextUtcDay(day: string) {
+  const timestamp = Date.parse(`${day}T00:00:00.000Z`);
+
+  if (Number.isNaN(timestamp)) {
+    return undefined;
+  }
+
+  return new Date(timestamp + 86_400_000).toISOString().slice(0, 10);
+}
+
+export function deriveStreakSummary(commits: readonly CommitRecord[]): StreakSummary {
+  if (commits.length === 0) {
+    return { status: "empty" };
+  }
+
+  const days = [...new Set(commits.map(parseCommitDay).filter((day): day is string => day !== undefined))].sort();
+
+  if (days.length === 0) {
+    return { status: "insufficient-dates" };
+  }
+
+  let longest = 1;
+  let active = 1;
+
+  for (let index = 1; index < days.length; index += 1) {
+    const previousDay = days[index - 1];
+    const currentDay = days[index];
+
+    if (previousDay && currentDay && nextUtcDay(previousDay) === currentDay) {
+      active += 1;
+    } else {
+      active = 1;
+    }
+
+    longest = Math.max(longest, active);
+  }
+
+  let current = 1;
+  for (let index = days.length - 1; index > 0; index -= 1) {
+    const previousDay = days[index - 1];
+    const currentDay = days[index];
+
+    if (previousDay && currentDay && nextUtcDay(previousDay) === currentDay) {
+      current += 1;
+    } else {
+      break;
+    }
+  }
+
+  return { status: "ready", current, longest, anchorDate: days[days.length - 1] ?? "" };
+}
+
+function totalAdditions(report: RepoReportData) {
+  return report.commits.reduce((sum, commit) => sum + commit.files.reduce((fileSum, file) => fileSum + file.additions, 0), 0);
+}
+
+function totalDeletions(report: RepoReportData) {
+  return report.commits.reduce((sum, commit) => sum + commit.files.reduce((fileSum, file) => fileSum + file.deletions, 0), 0);
+}
+
+function totalLinesOfCode(report: RepoReportData) {
+  return report.analysis.languages.reduce((sum, language) => sum + language.lines, 0);
+}
+
+function formatNumber(value: number) {
+  return new Intl.NumberFormat("en").format(value);
+}
+
+function formatCompact(value: number) {
+  return new Intl.NumberFormat("en", { notation: "compact", maximumFractionDigits: 1 }).format(value);
+}
+
+function GitHubMetaBar({ meta }: { readonly meta: GitHubRepoMeta }) {
+  const items: readonly string[] = [
+    ...(meta.stars !== undefined && meta.stars > 0 ? [`Stars ${formatCompact(meta.stars)}`] : []),
+    ...(meta.forks !== undefined && meta.forks > 0 ? [`Forks ${formatCompact(meta.forks)}`] : []),
+    ...(meta.license !== undefined && meta.license.length > 0 ? [`License ${meta.license}`] : []),
+    ...(meta.visibility !== undefined ? [meta.visibility === "private" ? "Private" : "Public"] : []),
+    ...(meta.openIssues !== undefined && meta.openIssues > 0 ? [`Issues ${formatCompact(meta.openIssues)}`] : []),
+    ...(meta.openPullRequests !== undefined && meta.openPullRequests > 0 ? [`PRs ${formatCompact(meta.openPullRequests)}`] : []),
+  ];
+
+  const topics = meta.topics ?? [];
+
+  if (items.length === 0 && topics.length === 0 && meta.homepageUrl === undefined) {
+    return null;
+  }
+
+  return (
+    <section className="flex flex-wrap items-center gap-x-5 gap-y-2 rounded-xl border border-border/50 bg-muted/25 px-4 py-3">
+      {items.map((item) => {
+        const spaceIndex = item.indexOf(" ");
+        const label = spaceIndex >= 0 ? item.slice(0, spaceIndex) : item;
+        const value = spaceIndex >= 0 ? item.slice(spaceIndex + 1) : undefined;
+        return (
+          <span key={item} className="text-sm text-muted-foreground">
+            {label}{value !== undefined ? (<>
+{" "}<strong className="font-medium text-foreground">{value}</strong>
+</>) : null}
+          </span>
+        );
+      })}
+      {meta.homepageUrl !== undefined && meta.homepageUrl.length > 0 ? (
+        <a
+          className="text-sm text-muted-foreground hover:text-foreground"
+          href={meta.homepageUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Homepage
+        </a>
+      ) : null}
+      {topics.length > 0 ? (
+        <div className="flex flex-wrap gap-1">
+          {topics.map((topic) => (
+            <span key={topic} className="rounded-full bg-muted px-2 py-0.5 text-xs text-muted-foreground">{topic}</span>
+          ))}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+function buildOverviewStats(report: RepoReportData) {
+  return [
+    { label: "Total commits", value: formatNumber(report.commits.length), description: "Commits included in this report" },
+    { label: "Contributors", value: formatNumber(report.contributors.length), description: "Unique author identities" },
+    { label: "Additions", value: formatNumber(totalAdditions(report)), description: "Lines added across file changes" },
+    { label: "Deletions", value: formatNumber(totalDeletions(report)), description: "Lines removed across file changes" },
+    { label: "LoC", value: formatNumber(totalLinesOfCode(report)), description: "Detected lines of code" },
+  ];
+}
+
+function StreakCard({ streak }: { readonly streak: StreakSummary }) {
+  if (streak.status === "empty") {
+    return (
+      <EmptyState
+        title="No streak data yet"
+        description="Streaks appear after the repository has at least one dated commit."
+      />
+    );
+  }
+
+  if (streak.status === "insufficient-dates") {
+    return (
+      <EmptyState
+        title="Streak data is unavailable"
+        description="The commits in this report do not include valid authored dates, so streaks cannot be derived."
+      />
+    );
+  }
+
+  return (
+    <Card className="h-full overflow-hidden shadow-none transition-transform duration-500 ease-out hover:-translate-y-0.5">
+      <CardHeader className="space-y-2">
+        <CardTitle className="text-base font-semibold tracking-tight text-foreground">Commit streak</CardTitle>
+        <p className="text-sm leading-6 text-muted-foreground">Consecutive UTC commit days ending at the latest commit in this report.</p>
+      </CardHeader>
+      <CardContent className="grid grid-flow-dense gap-4 sm:grid-cols-2">
+        <div>
+          <p className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Current</p>
+          <p className="mt-2 text-4xl font-semibold tracking-tight text-foreground">{streak.current}</p>
+          <p className="mt-2 text-xs leading-5 text-muted-foreground">Ending {streak.anchorDate}</p>
+        </div>
+        <div>
+          <p className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Longest</p>
+          <p className="mt-2 text-4xl font-semibold tracking-tight text-foreground">{streak.longest}</p>
+          <p className="mt-2 text-xs leading-5 text-muted-foreground">Best consecutive-day run</p>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function ChartPreview({ report }: { readonly report: RepoReportData }) {
+  const activity = deriveCommitActivityData(report);
+
+  if (activity.length === 0 || activity.every((point) => point.commits === 0)) {
+    return (
+      <EmptyState
+        title="No activity preview yet"
+        description="The mini chart needs at least one cadence point with commits."
+      />
+    );
+  }
+
+  return <CommitActivityChart data={activity} />;
+}
+
+export function RepoOverview({ report }: { readonly report: ReportData }) {
+  if (report.kind !== "repo") {
+    return (
+      <EmptyState
+        title="Repo overview is unavailable for scan reports"
+        description="This route expects a single-repository report. Open the scan overview for multi-repository aggregate evidence."
+      />
+    );
+  }
+
+  const githubMeta = report.repository.github;
+
+  if (report.commits.length === 0 && report.contributors.length === 0) {
+    return (
+      <div className="grid gap-6">
+        <StatsGrid stats={buildOverviewStats(report)} />
+        {githubMeta !== undefined ? <GitHubMetaBar meta={githubMeta} /> : null}
+        <EmptyState
+          title="This repository has no commit activity yet"
+          description="git-snitch found a repository report, but there are no commits or contributors to summarize. Charts and streaks will appear after activity exists."
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid gap-6">
+      <StatsGrid stats={buildOverviewStats(report)} />
+      {githubMeta !== undefined ? <GitHubMetaBar meta={githubMeta} /> : null}
+      <section aria-label="Repository overview previews" className="grid grid-flow-dense gap-6 lg:grid-cols-2">
+        <StreakCard streak={deriveStreakSummary(report.commits)} />
+        <ChartPreview report={report} />
+      </section>
+    </div>
+  );
+}

package/src/quality-hotspots-routes.tsx

@@ -0,0 +1,340 @@
+import { Card, CardContent, CardHeader, CardTitle } from "@git-snitch/ui/components/card";
+import { cn } from "@git-snitch/ui/lib/utils";
+
+import type { FileHotspot, QualitySignal, RepoReportData, ReportData } from "@git-snitch/core";
+
+import { EmptyState } from "./empty-state.js";
+import { HotspotsTable } from "./tables.js";
+
+type RepoRouteProps = {
+  readonly report: ReportData;
+};
+
+type HealthRating = "Strong" | "Watch" | "Strained" | "Unclear";
+
+const minimumConclusiveCommits = 3;
+const minimumConclusiveContributors = 2;
+
+type QualityMetric = {
+  readonly label: string;
+  readonly value: string;
+  readonly description: string;
+  readonly tone: "good" | "watch" | "risk" | "neutral";
+};
+
+function formatNumber(value: number) {
+  return new Intl.NumberFormat("en").format(value);
+}
+
+function repoDataMismatch(title: string) {
+  return (
+    <EmptyState
+      title={title}
+      description="This route expects a single-repository report. Scan reports use aggregate scan routes rather than repo-only quality views."
+    />
+  );
+}
+
+function repoFilename(report: RepoReportData, suffix: string) {
+  const safeName = report.repository.name.trim().replaceAll(/[^a-zA-Z0-9._-]+/g, "-").replaceAll(/^-|-$/g, "");
+  return `${safeName.length > 0 ? safeName : "repo"}-${suffix}`;
+}
+
+function commitChurn(report: RepoReportData) {
+  return report.commits.reduce(
+    (sum, commit) => sum + commit.files.reduce((fileSum, file) => fileSum + file.additions + file.deletions, 0),
+    0,
+  );
+}
+
+function averageCommitSize(report: RepoReportData) {
+  if (report.commits.length === 0) {
+    return 0;
+  }
+
+  return Math.round(commitChurn(report) / report.commits.length);
+}
+
+function busFactor(report: RepoReportData) {
+  const sortedCommitCounts = report.contributors.map((contributor) => contributor.commitCount).filter((count) => count > 0).sort((left, right) => right - left);
+  const totalCommits = sortedCommitCounts.reduce((sum, count) => sum + count, 0);
+
+  if (totalCommits === 0) {
+    return 0;
+  }
+
+  const threshold = totalCommits * 0.8;
+  let covered = 0;
+  let contributors = 0;
+
+  for (const count of sortedCommitCounts) {
+    covered += count;
+    contributors += 1;
+    if (covered >= threshold) {
+      return contributors;
+    }
+  }
+
+  return contributors;
+}
+
+function codeStability(report: RepoReportData) {
+  const additions = report.commits.reduce((sum, commit) => sum + commit.files.reduce((fileSum, file) => fileSum + file.additions, 0), 0);
+  const deletions = report.commits.reduce((sum, commit) => sum + commit.files.reduce((fileSum, file) => fileSum + file.deletions, 0), 0);
+
+  if (report.commits.length === 0) {
+    return 1;
+  }
+
+  if (deletions === 0) {
+    return additions > 0 ? 2 : 1;
+  }
+
+  return Math.round((additions / deletions) * 100) / 100;
+}
+
+function severityPenalty(signal: QualitySignal) {
+  if (signal.severity === "critical") {
+    return 24;
+  }
+  if (signal.severity === "warning") {
+    return 12;
+  }
+  return 6;
+}
+
+function hasConclusiveQualityEvidence(report: RepoReportData) {
+  return report.commits.length >= minimumConclusiveCommits && report.contributors.length >= minimumConclusiveContributors;
+}
+
+export function deriveHealthScore(report: RepoReportData) {
+  if (!hasConclusiveQualityEvidence(report)) {
+    return { score: 0, rating: "Unclear" satisfies HealthRating };
+  }
+
+  const signalPenalty = report.analysis.qualitySignals.reduce((sum, signal) => sum + severityPenalty(signal), 0);
+  const busFactorPenalty = report.commits.length > 0 && busFactor(report) <= 1 ? 16 : 0;
+  const hotspotPenalty = report.analysis.hotspots.some((hotspot) => hotspot.riskLevel.level === "high") ? 10 : 0;
+  const score = Math.max(0, Math.min(100, 100 - signalPenalty - busFactorPenalty - hotspotPenalty));
+
+  if (score >= 80) {
+    return { score, rating: "Strong" satisfies HealthRating };
+  }
+  if (score >= 55) {
+    return { score, rating: "Watch" satisfies HealthRating };
+  }
+  return { score, rating: "Strained" satisfies HealthRating };
+}
+
+function qualityMetrics(report: RepoReportData): readonly QualityMetric[] {
+  const factor = busFactor(report);
+  const averageSize = averageCommitSize(report);
+  const churn = commitChurn(report);
+  const stability = codeStability(report);
+
+  return [
+    {
+      label: "Bus factor",
+      value: factor === 0 ? "No commits" : formatNumber(factor),
+      description: "Contributors covering roughly 80% of observed commits.",
+      tone: factor === 0 ? "neutral" : factor <= 1 ? "risk" : factor <= 2 ? "watch" : "good",
+    },
+    {
+      label: "Avg commit size",
+      value: `${formatNumber(averageSize)} lines`,
+      description: "Mean changed lines per commit from file statistics.",
+      tone: averageSize === 0 ? "neutral" : averageSize > 500 ? "risk" : averageSize > 200 ? "watch" : "good",
+    },
+    {
+      label: "Churn",
+      value: `${formatNumber(churn)} lines`,
+      description: "Total additions and deletions in the selected repo scope.",
+      tone: churn === 0 ? "neutral" : churn > 5_000 ? "risk" : churn > 1_000 ? "watch" : "good",
+    },
+    {
+      label: "Stability ratio",
+      value: stability.toLocaleString("en"),
+      description: "Additions divided by deletions; sparse repos are marked explicitly.",
+      tone: report.commits.length === 0 ? "neutral" : stability > 3 || stability < 0.5 ? "watch" : "good",
+    },
+  ];
+}
+
+function metricToneClass(tone: QualityMetric["tone"]) {
+  if (tone === "risk") {
+    return "border-red-500/30 bg-red-500/10";
+  }
+  if (tone === "watch") {
+    return "border-amber-500/30 bg-amber-500/10";
+  }
+  if (tone === "good") {
+    return "border-emerald-500/30 bg-emerald-500/10";
+  }
+  return "border-border/70 bg-card/80";
+}
+
+function HealthScorePanel({ report }: { readonly report: RepoReportData }) {
+  const health = deriveHealthScore(report);
+  const hasEvidence = health.rating !== "Unclear";
+  const narrative = hasEvidence
+    ? "The score combines observed warning signals, ownership concentration, and high-risk files. Tiny repositories are treated as inconclusive instead of being dressed up as healthy."
+    : "There are not enough commits or contributors for a confident health label. Treat this repository as inconclusive until it has a larger evidence trail.";
+
+  return (
+    <section className="grid grid-flow-dense gap-5 rounded-3xl border border-border/70 bg-card/80 p-6 shadow-sm md:grid-cols-[minmax(0,0.8fr)_minmax(0,1.2fr)] md:items-center">
+      <div className="rounded-2xl border border-border/70 bg-background/70 p-6">
+        <p className="text-sm font-medium text-muted-foreground">Repository health score</p>
+        <div className="mt-3 flex items-end gap-2">
+          <span className="text-6xl font-semibold tracking-[-0.08em] text-foreground">{hasEvidence ? health.score : "—"}</span>
+          {hasEvidence ? <span className="pb-2 text-lg font-medium text-muted-foreground">/100</span> : null}
+        </div>
+        <p className="mt-3 text-base font-semibold text-foreground">{health.rating}</p>
+      </div>
+      <div className="max-w-4xl">
+        <h2 className="text-3xl font-semibold tracking-tight text-foreground md:text-4xl">Quality signals without hiding the evidence trail.</h2>
+        <p className="mt-4 text-sm leading-6 text-muted-foreground">{narrative}</p>
+      </div>
+    </section>
+  );
+}
+
+function QualityMetricCards({ report }: { readonly report: RepoReportData }) {
+  return (
+    <section aria-label="Quality metric cards" className="grid grid-flow-dense gap-4 md:grid-cols-2 xl:grid-cols-4">
+      {qualityMetrics(report).map((metric) => (
+        <Card key={metric.label} className={cn("overflow-hidden shadow-none transition-transform duration-500 ease-out hover:-translate-y-0.5", metricToneClass(metric.tone))}>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium text-muted-foreground">{metric.label}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-3xl font-semibold tracking-tight text-foreground">{metric.value}</p>
+            <p className="mt-3 text-xs leading-5 text-muted-foreground">{metric.description}</p>
+          </CardContent>
+        </Card>
+      ))}
+    </section>
+  );
+}
+
+function severityClass(severity: QualitySignal["severity"]) {
+  if (severity === "critical") {
+    return "border-red-500/30 bg-red-500/10 text-red-700 dark:text-red-300";
+  }
+  if (severity === "warning") {
+    return "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300";
+  }
+  return "border-blue-500/30 bg-blue-500/10 text-blue-700 dark:text-blue-300";
+}
+
+function RecommendationsList({ signals }: { readonly signals: readonly QualitySignal[] }) {
+  if (signals.length === 0) {
+    return (
+      <EmptyState
+        title="No quality recommendations yet"
+        description="git-snitch did not detect quality risks in the available report data. Empty and tiny repositories may simply not have enough evidence."
+      />
+    );
+  }
+
+  return (
+    <section className="rounded-2xl border border-border/70 bg-card/80 shadow-sm" aria-label="Quality recommendations">
+      <div className="border-b border-border/70 p-5">
+        <h2 className="text-2xl font-semibold tracking-tight text-foreground">Recommendations</h2>
+        <p className="mt-2 text-sm leading-6 text-muted-foreground">Prioritized actions generated from the report quality signals.</p>
+      </div>
+      <ol className="divide-y divide-border/70">
+        {signals.map((signal) => (
+          <li key={signal.id} className="grid gap-3 p-5 md:grid-cols-[auto_1fr] md:items-start">
+            <span className={cn("inline-flex w-fit rounded-full border px-2.5 py-1 text-xs font-semibold capitalize", severityClass(signal.severity))}>{signal.severity}</span>
+            <div>
+              <h3 className="font-semibold text-foreground">{signal.label}</h3>
+              <p className="mt-1 text-sm leading-6 text-muted-foreground">{signal.summary}</p>
+            </div>
+          </li>
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+function countRisk(hotspots: readonly FileHotspot[], level: FileHotspot["riskLevel"]["level"]) {
+  return hotspots.filter((hotspot) => hotspot.riskLevel.level === level).length;
+}
+
+function highestRisk(hotspots: readonly FileHotspot[]) {
+  const high = hotspots.find((hotspot) => hotspot.riskLevel.level === "high");
+  if (high) {
+    return high;
+  }
+
+  return hotspots.find((hotspot) => hotspot.riskLevel.level === "medium") ?? hotspots[0];
+}
+
+function RiskIndicators({ hotspots }: { readonly hotspots: readonly FileHotspot[] }) {
+  const topRisk = highestRisk(hotspots);
+
+  return (
+    <section aria-label="Hotspot risk indicators" className="grid grid-flow-dense gap-4 md:grid-cols-3">
+      <Card className="border-red-500/20 bg-red-500/10 shadow-none transition-transform duration-500 ease-out hover:-translate-y-0.5">
+        <CardHeader><CardTitle className="text-sm font-medium text-muted-foreground">High risk files</CardTitle></CardHeader>
+        <CardContent><p className="text-4xl font-semibold tracking-tight text-foreground">{formatNumber(countRisk(hotspots, "high"))}</p></CardContent>
+      </Card>
+      <Card className="border-amber-500/20 bg-amber-500/10 shadow-none transition-transform duration-500 ease-out hover:-translate-y-0.5">
+        <CardHeader><CardTitle className="text-sm font-medium text-muted-foreground">Medium risk files</CardTitle></CardHeader>
+        <CardContent><p className="text-4xl font-semibold tracking-tight text-foreground">{formatNumber(countRisk(hotspots, "medium"))}</p></CardContent>
+      </Card>
+      <Card className="shadow-none transition-transform duration-500 ease-out hover:-translate-y-0.5">
+        <CardHeader><CardTitle className="text-sm font-medium text-muted-foreground">Top hotspot</CardTitle></CardHeader>
+        <CardContent>
+          <p className="truncate font-mono text-sm font-semibold text-foreground">{topRisk?.path ?? "No file risk"}</p>
+          <p className="mt-2 text-xs text-muted-foreground">{topRisk ? `${formatNumber(topRisk.hotspotScore)} score from churn and contributors` : "No ranked file changes yet."}</p>
+        </CardContent>
+      </Card>
+    </section>
+  );
+}
+
+export function QualityRoute({ report }: RepoRouteProps) {
+  if (report.kind !== "repo") {
+    return repoDataMismatch("Quality is unavailable for scan reports");
+  }
+
+  const isTiny = !hasConclusiveQualityEvidence(report);
+
+  return (
+    <div className="grid gap-6">
+      <HealthScorePanel report={report} />
+      {isTiny ? (
+        <EmptyState
+          title="Quality evidence is sparse"
+          description={`This repository has too little activity for a confident health narrative. At least ${minimumConclusiveCommits} commits and ${minimumConclusiveContributors} contributors are needed before git-snitch labels quality as strong, watch, or strained.`}
+        />
+      ) : null}
+      <QualityMetricCards report={report} />
+      <RecommendationsList signals={report.analysis.qualitySignals} />
+    </div>
+  );
+}
+
+export function HotspotsRoute({ report }: RepoRouteProps) {
+  if (report.kind !== "repo") {
+    return repoDataMismatch("Hotspots are unavailable for scan reports");
+  }
+
+  const hotspots = report.analysis.hotspots;
+
+  return (
+    <div className="grid gap-6">
+      <section className="rounded-3xl border border-border/70 bg-card/80 p-6 shadow-sm">
+        <div className="max-w-4xl">
+          <h2 className="text-3xl font-semibold tracking-tight text-foreground md:text-4xl">Hotspots rank files where churn, frequency, and shared ownership intersect.</h2>
+          <p className="mt-4 text-sm leading-6 text-muted-foreground">
+            Use this route to find files that deserve review before they become expensive coordination points. Low activity repositories show an explicit empty state instead of a fabricated risk map.
+          </p>
+        </div>
+      </section>
+      {hotspots.length > 0 ? <RiskIndicators hotspots={hotspots} /> : null}
+      <HotspotsTable hotspots={hotspots} exportFilename={repoFilename(report, "hotspots.csv")} remoteUrl={report.repository.remoteUrl} currentBranch={report.repository.currentBranch} />
+    </div>
+  );
+}

package/src/remote-urls.ts

@@ -0,0 +1,97 @@
+export type GitProvider = "github" | "gitlab" | "bitbucket" | "unknown";
+
+const SCP_REMOTE = /^git@([^:]+):(.+?)$/;
+
+export function normalizeRemoteToWebUrl(remoteUrl: string): string {
+  const trimmed = remoteUrl.replace(/\/+$/, "");
+
+  const scpMatch = SCP_REMOTE.exec(trimmed);
+  if (scpMatch && scpMatch[1] !== undefined && scpMatch[2] !== undefined) {
+    return `https://${scpMatch[1]}/${scpMatch[2].replace(/\.git$/, "")}`;
+  }
+
+  if (trimmed.startsWith("ssh://")) {
+    try {
+      const parsed = new URL(trimmed);
+      const path = parsed.pathname.replace(/^\/+/, "").replace(/\.git$/, "");
+      return `https://${parsed.hostname}/${path}`;
+    } catch {
+      return trimmed.replace(/\.git$/, "");
+    }
+  }
+
+  return trimmed.replace(/\.git$/, "");
+}
+
+export function detectProvider(remoteUrl: string | undefined): GitProvider {
+  if (remoteUrl === undefined) {
+    return "unknown";
+  }
+
+  const host = extractHost(remoteUrl);
+  if (host === undefined) {
+    return "unknown";
+  }
+
+  if (host === "github.com" || host.endsWith(".github.com")) {
+    return "github";
+  }
+  if (host === "gitlab.com" || host.endsWith(".gitlab.com")) {
+    return "gitlab";
+  }
+  if (host === "bitbucket.org" || host.endsWith(".bitbucket.org")) {
+    return "bitbucket";
+  }
+
+  return "unknown";
+}
+
+export function buildCommitUrl(remoteUrl: string | undefined, hash: string): string | undefined {
+  if (remoteUrl === undefined) {
+    return undefined;
+  }
+
+  const provider = detectProvider(remoteUrl);
+  const base = normalizeRemoteToWebUrl(remoteUrl);
+
+  switch (provider) {
+    case "github":
+      return `${base}/commit/${hash}`;
+    case "gitlab":
+      return `${base}/-/commit/${hash}`;
+    case "bitbucket":
+      return `${base}/commits/${hash}`;
+    default:
+      return `${base}/commit/${hash}`;
+  }
+}
+
+export function buildFileUrl(remoteUrl: string | undefined, branch: string | undefined, filePath: string): string | undefined {
+  if (remoteUrl === undefined || branch === undefined) {
+    return undefined;
+  }
+
+  const provider = detectProvider(remoteUrl);
+  const base = normalizeRemoteToWebUrl(remoteUrl);
+
+  switch (provider) {
+    case "github":
+      return `${base}/blob/${branch}/${filePath}`;
+    case "gitlab":
+      return `${base}/-/blob/${branch}/${filePath}`;
+    case "bitbucket":
+      return `${base}/src/${branch}/${filePath}`;
+    default:
+      return `${base}/blob/${branch}/${filePath}`;
+  }
+}
+
+function extractHost(remoteUrl: string): string | undefined {
+  try {
+    const parsed = new URL(remoteUrl);
+    return parsed.hostname;
+  } catch {
+    const scpMatch = SCP_REMOTE.exec(remoteUrl);
+    return scpMatch?.[1];
+  }
+}