Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

16.6 KB
Raw Blame
"use client";

import { useCallback } from "react";
import Link from "next/link";
import useSWR from "swr";
import { ArrowRight, Flame, Bug } from "lucide-react";
import { cn } from "@/lib/utils/cn";
import { getGitMetadata } from "@/lib/api/git";
import { summarizeFixHistory } from "@repowise-dev/ui/lib/fix-history";
import { DocsReader } from "@repowise-dev/ui/docs/docs-reader";
import { docsPagePath, fileEntityPath } from "@repowise-dev/ui/shared/entity";
import { isModelWrittenType } from "@repowise-dev/ui/lib/page-types";
import { PageGenerateButton } from "./page-generate-button";
import { Badge } from "@repowise-dev/ui/ui/badge";
import { Skeleton } from "@repowise-dev/ui/ui/skeleton";
import { VersionHistoryWrapper } from "@/components/wiki/version-history";
import { SecurityPanelWrapper } from "@/components/wiki/security-panel";
import { useGraphMetrics, useCallersCallees } from "@/lib/hooks/use-graph";
import type { ReaderPersona } from "@repowise-dev/ui/docs/reader-persona";
import type { DocPage, DocPageSummary } from "@repowise-dev/types/docs";
import type { PageResponse, PageSummary } from "@/lib/api/types";
import { useTranslations } from "next-intl";

function PercentileBar({ value, label }: { value: number; label: string }) {
  const t = useTranslations("docs");
  const pct = 100 - value;
  return (
    <div className="flex items-center justify-between gap-2">
      <span className="text-xs text-[var(--color-text-tertiary)] shrink-0">{label}</span>
      <div className="flex items-center gap-1.5">
        <div className="w-16 h-1.5 rounded-full bg-[var(--color-bg-elevated)] overflow-hidden">
          <div
            className={cn(
              "h-full rounded-full",
              value >= 75 ? "bg-[var(--color-success)]" : value >= 50 ? "bg-[var(--color-warning)]" : "bg-[var(--color-text-tertiary)]",
            )}
            style={{ width: `${value}%` }}
          />
        </div>
        <span className={cn(
          "text-[10px] font-mono tabular-nums w-10 text-right",
          value >= 75 ? "text-[var(--color-success)]" : value >= 50 ? "text-[var(--color-warning)]" : "text-[var(--color-text-tertiary)]",
        )}>
          {t("viewer.topPercent", { pct })}
        </span>
      </div>
    </div>
  );
}

function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: string }) {
  const t = useTranslations("docs");
  const nodeId = targetPath;
  const { metrics, isLoading: metricsLoading } = useGraphMetrics(repoId, nodeId);
  const symbolNodeId = targetPath.includes("::") ? targetPath : null;
  const { data: callData } = useCallersCallees(repoId, symbolNodeId);

  if (metricsLoading) {
    return (
      <div className="space-y-3">
        <Skeleton className="h-4 w-20" />
        <Skeleton className="h-3 w-full" />
        <Skeleton className="h-3 w-full" />
        <Skeleton className="h-3 w-3/4" />
      </div>
    );
  }

  // No graph data — render nothing rather than announcing the absence.
  if (!metrics) return null;

  return (
    <div className="space-y-4">
      {/* Graph importance. No section header of its own — the rail groups these
          under one "Signals" label, so the rows speak for themselves. */}
      <div>
        <div className="space-y-2">
          <PercentileBar value={metrics.pagerank_percentile} label="PageRank" />
          {metrics.betweenness_scored === false ? (
            // Never measured, so a percentile bar would draw a rank it does not have.
            <div className="flex items-center justify-between">
              <span className="text-xs text-[var(--color-text-tertiary)]">
                {t("viewer.centrality")}
              </span>
              <span className="text-xs text-[var(--color-text-tertiary)]">
                {t("viewer.notScored")}
              </span>
            </div>
          ) : (
            <PercentileBar
              value={metrics.betweenness_percentile}
              label={t("viewer.centrality")}
            />
          )}
          <div className="flex items-center justify-between">
            <span className="text-xs text-[var(--color-text-tertiary)]">
              {t("viewer.degree")}
            </span>
            <span className="text-xs font-mono text-[var(--color-text-secondary)]">
              {t("viewer.degreeValue", {
                inbound: metrics.in_degree,
                outbound: metrics.out_degree,
              })}
            </span>
          </div>
          {metrics.is_entry_point && (
            <Badge variant="accent" className="text-[10px]">
              {t("viewer.entryPoint")}
            </Badge>
          )}
        </div>
      </div>

      {/* Community — a single value, so it renders as a labelled row like the
          rest rather than as its own titled section. */}
      {metrics.community_label && (
        <div className="flex items-center justify-between gap-2">
          <span className="text-xs text-[var(--color-text-tertiary)]">
            {t("viewer.community")}
          </span>
          <Link
            href={`/repos/${repoId}/architecture?view=communities`}
            className="inline-flex items-center gap-1 truncate text-xs text-[var(--color-accent)] hover:underline"
          >
            {metrics.community_label}
            <ArrowRight className="h-2.5 w-2.5 shrink-0" />
          </Link>
        </div>
      )}

      {/* Callers/Callees (for symbol pages) */}
      {callData && (callData.caller_count > 0 || callData.callee_count > 0) && (
        <div>
          {callData.caller_count > 0 && (
            <div className="mb-2">
              <p className="text-[10px] text-[var(--color-text-tertiary)] mb-1">
                {t("viewer.calledBy", { count: callData.caller_count })}
              </p>
              {callData.callers.slice(0, 5).map((c) => (
                <p key={c.symbol_id} className="text-xs font-mono text-[var(--color-text-secondary)] truncate pl-2" title={c.symbol_id}>
                  {c.name}
                </p>
              ))}
            </div>
          )}
          {callData.callee_count > 0 && (
            <div>
              <p className="text-[10px] text-[var(--color-text-tertiary)] mb-1">
                {t("viewer.calls", { count: callData.callee_count })}
              </p>
              {callData.callees.slice(0, 5).map((c) => (
                <p key={c.symbol_id} className="text-xs font-mono text-[var(--color-text-secondary)] truncate pl-2" title={c.symbol_id}>
                  {c.name}
                </p>
              ))}
            </div>
          )}
        </div>
      )}
    </div>
  );
}

/** Page types whose `target_path` is a file or a `file::symbol` id. */
const SIGNAL_PAGE_TYPES = new Set(["file_page", "symbol_spotlight", "api_contract", "infra_page"]);

/**
 * Consolidated "At a glance" signals for a file page — hotspot, ownership,
 * churn, bus factor — pulled from the git-metadata endpoint so the reader
 * doesn't have to leave the doc to learn how risky/owned a file is.
 * Renders nothing for non-file pages or files without git history.
 */
function AtAGlance({ repoId, targetPath }: { repoId: string; targetPath: string }) {
  const t = useTranslations("docs");
  const isFile =
    !!targetPath &&
    !targetPath.includes("::") &&
    !targetPath.startsWith("onboarding/") &&
    !targetPath.startsWith("layer:");
  const { data } = useSWR(
    isFile ? `git-meta:${repoId}:${targetPath}` : null,
    () => getGitMetadata(repoId, targetPath),
    { revalidateOnFocus: false, shouldRetryOnError: false },
  );
  if (!data || data.commit_count_total === 0) return null;

  const churnTop = Math.max(1, 100 - Math.round(data.churn_percentile));
  // Null for a file with no counted fixes, so the panel says nothing new.
  const fix = summarizeFixHistory(
    data.prior_defect_count,
    data.last_fix_at,
    data.bug_magnet,
  );
  return (
    <div>
      {/* Leads the Signals list: the chips are the fastest read on the page,
          and they carry their own meaning without a header over them. */}
      <div className="flex flex-wrap gap-1.5">
        {data.is_hotspot && (
          <Badge variant="outline" className="text-[10px] border-[var(--color-warning)]/40 text-[var(--color-warning)]">
            <Flame className="h-2.5 w-2.5 mr-1" />
            {t("viewer.hotspot", { pct: churnTop })}
          </Badge>
        )}
        {data.is_stable && !data.is_hotspot && (
          <Badge variant="outline" className="text-[10px]">
            {t("viewer.stable")}
          </Badge>
        )}
        {data.bus_factor === 1 && (
          <Badge variant="outline" className="text-[10px] border-[var(--color-warning)]/40 text-[var(--color-warning)]">
            {t("viewer.busFactorOne")}
          </Badge>
        )}
        {/* Plain outline, like every other chip in this row. It used to carry
            --color-error, which made it the loudest mark on the panel and put
            it in the same colour vocabulary the health bands use. */}
        {fix?.magnet && (
          <Badge
            variant="outline"
            className="text-[10px]"
            title={t("viewer.bugMagnetTitle", { age: fix.age ?? "" })}
          >
            <Bug className="h-2.5 w-2.5 mr-1" />
            {t("viewer.bugMagnet")}
          </Badge>
        )}
      </div>
      <div className="mt-2 space-y-1 text-xs text-[var(--color-text-secondary)]">
        {data.primary_owner_name && (
          <div className="flex items-center justify-between gap-2">
            <span className="text-[var(--color-text-tertiary)]">
              {t("viewer.owner")}
            </span>
            <span className="truncate" title={data.primary_owner_name}>
              {data.primary_owner_name}
              {data.primary_owner_commit_pct != null &&
                ` · ${Math.round(data.primary_owner_commit_pct * 100)}%`}
            </span>
          </div>
        )}
        <div className="flex items-center justify-between gap-2">
          <span className="text-[var(--color-text-tertiary)]">
            {t("viewer.commits90d")}
          </span>
          <span className="font-mono">{data.commit_count_90d}</span>
        </div>
        {fix && (
          <div className="flex items-center justify-between gap-2">
            <span className="text-[var(--color-text-tertiary)]">
              {t("viewer.bugFixes")}
            </span>
            <span
              className="font-mono"
              title={t("viewer.bugFixesTitle")}
            >
              {fix.count}
              {fix.age && ` · last ${fix.age}`}
            </span>
          </div>
        )}
        <div className="flex items-center justify-between gap-2">
          <span className="text-[var(--color-text-tertiary)]">
            {t("viewer.contributors")}
          </span>
          <span className="font-mono">{data.contributor_count}</span>
        </div>
        {(data.agent_commit_count ?? 0) > 0 && (
          // Share of commits with a known source, beside that coverage;
          // withheld below the coverage floor. Unknown is never human.
          <div className="flex items-center justify-between gap-2">
            <span className="text-[var(--color-text-tertiary)]">Agent-authored</span>
            <span className="font-mono">
              {data.agent_authored_pct != null
                ? `≥${Math.round(data.agent_authored_pct * 100)}% of covered · `
                : ""}
              {data.agent_commit_count} · coverage{" "}
              {Math.round((data.attribution_coverage ?? 0) * 100)}%
            </span>
          </div>
        )}
        {data.original_path && (
          <div className="flex items-center justify-between gap-2">
            <span className="shrink-0 text-[var(--color-text-tertiary)]">
              {t("viewer.renamedFrom")}
            </span>
            <span className="truncate font-mono" title={data.original_path}>
              {data.original_path}
            </span>
          </div>
        )}
        {data.commit_count_capped && (
          <p className="text-[10px] text-[var(--color-text-tertiary)]">
            {t("viewer.historyCapped")}
          </p>
        )}
      </div>
    </div>
  );
}

interface DocsViewerProps {
  page: PageResponse | null;
  /** Full page list — powers hierarchical breadcrumbs and prev/next. Rows
   *  carry no bodies; the page being read is fetched on its own. */
  pages?: PageSummary[];
  repoId: string;
  isLoading?: boolean;
  /** Select another page in-place (breadcrumb / prev-next / wiki links). */
  onSelectPage?: (page: DocPageSummary) => void;
  persona: ReaderPersona;
  sidebarOpen: boolean;
  /** Called once an inline page upgrade completes so the host refreshes. */
  onGenerated?: () => void;
  /** A `?page=` id whose fetch settled with nothing. See `DocsReader`. */
  missingPageId?: string | undefined;
}

/**
 * Web data wrapper around the presentational ``DocsReader`` ui shell. Owns the
 * data-bound rail sections (git "at a glance", graph intelligence, version
 * history) and the Next route shape; the reader layout itself lives in ui so
 * the redesign ships through the package bump.
 */
export function DocsViewer({
  page,
  pages = [],
  repoId,
  isLoading,
  onSelectPage,
  persona,
  sidebarOpen,
  onGenerated,
  missingPageId,
}: DocsViewerProps) {
  const t = useTranslations("docs");
  const buildPageHref = useCallback(
    (pageId: string) => docsPagePath(`/repos/${repoId}`, pageId),
    [repoId],
  );

  const buildFileHref = useCallback(
    (filePath: string) => fileEntityPath(`/repos/${repoId}`, filePath),
    [repoId],
  );

  // Fall back to the wiki deep-link route only when the target isn't in the
  // loaded list (which itself opens the unified reader via redirect).
  const onNavigatePageId = useCallback(
    (pageId: string) => {
      window.location.href = `/repos/${repoId}/wiki/${encodeURIComponent(pageId)}`;
    },
    [repoId],
  );

  const targetPath = page?.target_path ?? "";
  // Decided by page type, not path shape: only these target a file or a
  // symbol. Any other target (the repo overview's repo name, a module's
  // directory, a cycle id) is no file, so every row below asked the API for
  // it and got a 404; module pages already have their own history card.
  const showSignals = !!targetPath && SIGNAL_PAGE_TYPES.has(page?.page_type ?? "");
  // Security findings only make sense for real source files.
  const isFilePath =
    showSignals &&
    !targetPath.includes("::") &&
    !targetPath.startsWith("onboarding/") &&
    !targetPath.startsWith("layer:");

  return (
    <DocsReader
      page={page as unknown as DocPage | null}
      pages={pages}
      repoId={repoId}
      isLoading={isLoading}
      onSelectPage={onSelectPage}
      onNavigatePageId={onNavigatePageId}
      persona={persona}
      sidebarOpen={sidebarOpen}
      buildPageHref={buildPageHref}
      buildFileHref={buildFileHref}
      missingPageId={missingPageId}
      LinkComponent={Link}
      // The page's own model action sits in its metadata row, on the page
      // types a model writes. Not passed as `upgradeSlot` as well: one action
      // per page, not a second copy at the foot.
      pageActionSlot={
        page && isModelWrittenType(page.page_type) ? (
          <PageGenerateButton
            page={page}
            repoId={repoId}
            onGenerated={onGenerated}
          />
        ) : undefined
      }
      freshnessHref={`/repos/${repoId}/docs/drift`}
      freshnessLabels={{
        stale: t("viewer.freshness.stale"),
        outdated: t("viewer.freshness.outdated"),
      }}
      versionHistorySlot={
        page ? (
          <VersionHistoryWrapper
            pageId={page.id}
            currentVersion={page.version}
            currentContent={page.content}
          />
        ) : undefined
      }
      intelligenceSlot={
        showSignals ? (
          // One "Signals" block, not five. At a glance, Importance, Community,
          // Call graph and Security each announced themselves with their own
          // uppercase label over a handful of rows, so the rail was mostly
          // label. They answer one question between them — what should I know
          // about this code before I touch it — so they read as one list.
          <div>
            <p className="mb-2.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
              {t("viewer.signals")}
            </p>
            <div className="flex flex-col gap-4">
              <AtAGlance repoId={repoId} targetPath={targetPath} />
              <DocsSidebar repoId={repoId} targetPath={targetPath} />
              {isFilePath && (
                <SecurityPanelWrapper repoId={repoId} filePath={targetPath} />
              )}
            </div>
          </div>
        ) : undefined
      }
    />
  );
}