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.

14.0 KB
Raw Blame
"use client";

import { useCallback, useMemo, useState } from "react";
import useSWR from "swr";
import { useQueryState } from "nuqs";
import { useSearchParams } from "next/navigation";
import { GraphFlow } from "@/components/graph/graph-flow";
import { GraphDocPanel } from "@/components/graph/graph-doc-panel";
import { GraphTruncationBanner } from "@repowise-dev/ui/graph/graph-truncation-banner";
import {
  GraphScopeSwitcher,
  GraphNarrowingSelect,
  type GraphScope,
} from "@repowise-dev/ui/graph/graph-scope-controls";
import type { ModuleGroup } from "@repowise-dev/ui/graph/use-module-filter";
import { getGraph } from "@/lib/api/graph";
import { useCommunities } from "@/lib/hooks/use-graph";
import type { GraphExportResponse } from "@/lib/api/types";
import { PRODUCTION_ONLY, type GraphPopulation } from "@repowise-dev/types/graph";
import { useTranslations } from "next-intl";
import { useGraphMapCopy } from "@/components/graph/use-graph-map-copy";

type ViewMode = "full" | "architecture" | "dead" | "hotfiles" | "unified";
type ColorMode = "language" | "community";
type Scope = "communities" | "files";

// `?colorMode=risk` links predate the removal of that lens; an unlisted value
// falls through to the "community" default rather than erroring.
const VALID_COLOR_MODES = new Set<ColorMode>(["language", "community"]);

/** `?show=tests,docs` ↔ the population flags. Absent or empty = production only.
 *  `external` rides in the same list: it is the same question ("which files
 *  that are not this repo's own code are drawn"), asked of the Files view. */
const POPULATION_KEYS = ["tests", "examples", "docs"] as const;
function parseShow(raw: string | null): GraphPopulation & { external: boolean } {
  const on = new Set((raw ?? "").split(",").map((s) => s.trim()));
  return {
    tests: on.has("tests"),
    examples: on.has("examples"),
    docs: on.has("docs"),
    external: on.has("external"),
  };
}
function serializeShow(p: GraphPopulation, external: boolean): string | null {
  const on: string[] = POPULATION_KEYS.filter((k) => p[k]);
  if (external) on.push("external");
  return on.length ? on.join(",") : null;
}

/** Scope + signal → the canvas's internal ViewMode. The overlay wins, because
 *  dead/hot are only ever drawn on the file graph. */
function toViewMode(scope: Scope, signal: string | null): ViewMode {
  if (scope === "communities") return "architecture";
  if (signal === "dead") return "dead";
  if (signal === "hot") return "hotfiles";
  return "full";
}

export function GraphView({
  repoId,
  scope,
  onScopeChange,
}: {
  repoId: string;
  /** Controlled by the page, which owns `?view=`. */
  scope: Scope;
  /** The page owns `?view=`, so a scope the canvas does not draw (the tree)
   *  is handed straight up rather than swallowed here. */
  onScopeChange: (scope: GraphScope) => void;
}) {
  const t = useTranslations("architecture");
  const mapCopy = useGraphMapCopy();
  const searchParams = useSearchParams();
  const initialNode = searchParams.get("node");

  const colorModeParam = searchParams.get("colorMode");
  const initialColorMode = VALID_COLOR_MODES.has((colorModeParam ?? "") as ColorMode)
    ? (colorModeParam as ColorMode)
    : undefined;

  const [, setSelectedNode] = useQueryState("node");
  const [, setColorModeParam] = useQueryState("colorMode");
  const [signal, setSignal] = useQueryState("signal");
  const [activeModule, setActiveModule] = useQueryState("module");
  // The drill-down, as URL state, so "inside this community" is a link you can
  // share and restore. Written with nuqs' default `history: "replace"`, like
  // every other param on this page, so Back leaves the page rather than
  // stepping out of the community — the breadcrumb and Escape are the way up.
  const [communityParam, setCommunityParam] = useQueryState("community");
  const [showParam, setShowParam] = useQueryState("show");
  const show = useMemo(() => parseShow(showParam), [showParam]);
  const population = useMemo<GraphPopulation>(
    () =>
      showParam
        ? { tests: show.tests, examples: show.examples, docs: show.docs }
        : PRODUCTION_ONLY,
    [showParam, show],
  );
  const handlePopulationChange = useCallback(
    (next: GraphPopulation) => {
      void setShowParam(serializeShow(next, show.external));
    },
    [setShowParam, show.external],
  );
  const handleShowExternalChange = useCallback(
    (next: boolean) => {
      void setShowParam(serializeShow(population, next));
    },
    [setShowParam, population],
  );
  const [docNodeId, setDocNodeId] = useState<string | null>(null);
  const [graphLimit, setGraphLimit] = useState<number | undefined>(undefined);
  const [moduleGroups, setModuleGroups] = useState<ModuleGroup[]>([]);

  // A pinned node is always a file, so a `?node=` link forces the file scope
  // however the URL spells the rest.
  const effectiveScope: Scope = initialNode ? "files" : scope;
  const viewMode = toViewMode(effectiveScope, signal);

  // A non-numeric or absent `?community=` is simply "not drilled in", the same
  // as a bad `?colorMode=`: an old link degrades, it does not error.
  // Matched rather than coerced: `Number("")` and `Number(" ")` are both 0, so
  // a bare `?community=` would resolve to community zero, which is a real one.
  const activeCommunity =
    effectiveScope === "files" && communityParam !== null && /^\d+$/.test(communityParam)
      ? Number(communityParam)
      : null;

  // The whole-repo file graph is not population-filtered, so its labels and
  // narrowing list are not either.
  const { communities } = useCommunities(
    repoId,
    effectiveScope === "communities" || activeCommunity !== null ? population : undefined,
  );

  // Only the unfiltered file scope renders the capped `/api/graph` payload.
  // The constellation, and each of the dead/hot signals, has its own endpoint —
  // so neither the fetch nor the truncation banner belongs to them. The banner
  // used to show under the signals too, announcing "1,500 of 3,194 files" over
  // a canvas drawing 734 nodes that came from somewhere else entirely. An
  // entered community brings its own payload for the same reason.
  const usesFullGraph = effectiveScope === "files" && !signal && activeCommunity === null;

  const { data: graphData } = useSWR<GraphExportResponse>(
    usesFullGraph ? `graph:${repoId}:${graphLimit ?? "default"}` : null,
    () => getGraph(repoId, graphLimit),
    { revalidateOnFocus: false, revalidateOnReconnect: false },
  );

  // Click a file node → open doc panel
  const handleNodeClick = useCallback(
    (nodeId: string, nodeType: string) => {
      if (nodeType !== "moduleGroup") {
        setDocNodeId((prev) => (prev === nodeId ? null : nodeId));
        void setSelectedNode(nodeId);
      }
    },
    [setSelectedNode],
  );

  // Double click or context menu "View Docs"
  const handleNodeViewDocs = useCallback(
    (nodeId: string) => {
      setDocNodeId((prev) => (prev === nodeId ? null : nodeId));
      void setSelectedNode(nodeId);
    },
    [setSelectedNode],
  );

  // The rail holds one panel, and the doc panel outranks the inspector, so a
  // doc left open would mask every later selection. Drop it once the selection
  // moves elsewhere.
  const handleSelectedNodeChange = useCallback((nodeId: string | null) => {
    setDocNodeId((prev) => (prev !== null && prev !== nodeId ? null : prev));
  }, []);

  // Opening a community also replaces the doc panel.
  const handleCommunityPanelOpen = useCallback(() => {
    setDocNodeId(null);
  }, []);

  // The canvas still owns the dead/hot node filter, and reports it as a
  // ViewMode. Scope changes never arrive this way any more — the switcher in
  // the header drives those — so this only has to keep `?signal=` honest.
  const handleViewModeChange = useCallback(
    (mode: ViewMode) => {
      void setSignal(mode === "dead" ? "dead" : mode === "hotfiles" ? "hot" : null);
    },
    [setSignal],
  );

  const handleColorModeChange = useCallback(
    (mode: ColorMode) => {
      void setColorModeParam(mode);
    },
    [setColorModeParam],
  );

  // "See all of them grouped" from the truncation banner: the whole repo, at
  // the scale where all of it fits.
  const handleSwitchToArchitecture = useCallback(() => {
    onScopeChange("communities");
  }, [onScopeChange]);

  const handleScopeChange = useCallback(
    (next: GraphScope) => {
      // Narrowing is a file-scope concept, so it does not survive a trip to the
      // constellation. It does not survive a trip *back* either: a
      // `?view=communities&community=3` link (hand-edited, or an old share)
      // renders the constellation with the param still set, and without this
      // clicking "Files" would drop the reader inside community 3 rather than
      // in the file graph they asked for.
      //
      // The tree is included: it is not narrowed by `?module=` or `?community=`
      // either, and a pin left set would be there when the reader came back to
      // the canvas.
      void setActiveModule(null);
      void setCommunityParam(null);
      // `?node=` forces the file scope for as long as it is set, so leaving it
      // behind makes every later scope change a no-op. Asking for a scope is
      // asking to stop looking at one pinned node.
      void setSelectedNode(null);
      onScopeChange(next);
    },
    [onScopeChange, setActiveModule, setCommunityParam, setSelectedNode],
  );

  // Entering or leaving a community, from the canvas (hub double-click, the
  // panel, Escape, the breadcrumb) or from the narrowing control. Entering
  // implies the file scope; leaving returns to the constellation the community
  // came from, which is where a community is a thing you can see.
  const handleActiveCommunityChange = useCallback(
    (next: number | null) => {
      void setCommunityParam(next === null ? null : String(next));
      // Same reason as the scope switcher: a `?node=` left over from opening a
      // file's docs inside the community would pin the file scope, so leaving
      // would land on the whole-repo file graph under a "Communities" URL.
      void setSelectedNode(null);
      if (next !== null) {
        void setActiveModule(null);
        // A slice is its own payload and was never filtered to dead or hot
        // files, so a `?signal=` carried in would caption it with counts that
        // describe a graph nobody is looking at.
        void setSignal(null);
        onScopeChange("files");
      } else {
        onScopeChange("communities");
      }
    },
    [setCommunityParam, setActiveModule, setSelectedNode, setSignal, onScopeChange],
  );

  const handleNarrowingChange = useCallback(
    ({ module, community }: { module: string | null; community: number | null }) => {
      // Community picks route through the same handler the canvas uses, so one
      // door does the reconciling (drop the `?node=` pin, drop `?signal=`, keep
      // the scope honest) however the reader asked.
      if (community !== null) {
        handleActiveCommunityChange(community);
        return;
      }
      void setCommunityParam(null);
      void setActiveModule(module);
    },
    [handleActiveCommunityChange, setCommunityParam, setActiveModule],
  );

  const isCommunities = effectiveScope === "communities";

  const headerControls = useMemo(
    () => (
      <div className="flex flex-wrap items-center gap-2">
        {!isCommunities && (
          <GraphNarrowingSelect
            modules={moduleGroups}
            communities={communities}
            activeModule={activeModule}
            activeCommunity={activeCommunity}
            onChange={handleNarrowingChange}
            copy={mapCopy.narrowing}
          />
        )}
        <GraphScopeSwitcher
          scope={effectiveScope}
          onScopeChange={handleScopeChange}
          copy={mapCopy.scope}
        />
      </div>
    ),
    [
      isCommunities,
      moduleGroups,
      communities,
      activeModule,
      activeCommunity,
      handleNarrowingChange,
      effectiveScope,
      handleScopeChange,
      mapCopy,
    ],
  );

  return (
    <GraphFlow
      repoId={repoId}
      // No title. The tab above says "Map" and the scope switcher says which
      // zoom you are at; the one line left is what to do with what you see.
      description={
        isCommunities
          ? t("graph.communitiesDescription")
          : t("graph.filesDescription")
      }
      headerActions={headerControls}
      banner={
        // Only when the file scope actually got capped.
        usesFullGraph && graphData?.truncated && graphData.total_node_count != null ? (
          <GraphTruncationBanner
            shown={graphData.nodes.length}
            total={graphData.total_node_count}
            limit={graphLimit ?? graphData.nodes.length}
            onLoadMore={(nextLimit) => setGraphLimit(nextLimit)}
            onSwitchToArchitecture={handleSwitchToArchitecture}
            copy={mapCopy.truncation}
          />
        ) : undefined
      }
      rail={
        docNodeId ? (
          <GraphDocPanel
            repoId={repoId}
            nodeId={docNodeId}
            onClose={() => setDocNodeId(null)}
          />
        ) : undefined
      }
      // Scope is controlled: `?view=` is the single source of truth, so
      // back/forward and shared links restore it without a remount.
      viewMode={viewMode}
      activeModule={activeModule}
      activeCommunity={activeCommunity}
      onActiveCommunityChange={handleActiveCommunityChange}
      population={population}
      onPopulationChange={handlePopulationChange}
      showExternal={show.external}
      onShowExternalChange={handleShowExternalChange}
      // Same value the banner reports, so the caption and the canvas can
      // never disagree about how many files are drawn.
      graphLimit={graphLimit}
      onModuleGroupsChange={setModuleGroups}
      colorMode={initialColorMode ?? "community"}
      initialSelectedNode={initialNode}
      onNodeClick={handleNodeClick}
      onNodeViewDocs={handleNodeViewDocs}
      onCommunityPanelOpen={handleCommunityPanelOpen}
      onSelectedNodeChange={handleSelectedNodeChange}
      onViewModeChange={handleViewModeChange}
      onColorModeChange={handleColorModeChange}
    />
  );
}