Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"use client";
/**
* CodeGraphTree — the dependency graph as a collapsible outline.
*
* The canvas draws one circle per file and one line per import, and at repo
* scale neither the line nor its label can be read: `imported_names` reaches
* the client on every edge already, and nothing renders it. This is the same
* payload in the other shape a reader knows how to walk. A directory tree, with
* every file openable in place to show the names it imports and which file each
* name comes from.
*
* Nothing here is fetched, curated or hardcoded: the outline, the counts and
* the type lists are all derived from the payload the canvas is drawing, so the
* two surfaces cannot disagree, and a revalidation or a stepped-up node cap
* updates this one too.
*
* Presentational. The component owns only which rows are open; data and links
* arrive as props, and `packages/web` hosts the wrapper that fetches them.
*/
import { useMemo, useState, type ElementType } from "react";
import {
ChevronDown,
ChevronRight,
FileCode,
Folder,
FolderOpen,
ListTree,
} from "lucide-react";
import { cn } from "../lib/cn";
import { formatNumber, truncatePath } from "../lib/format";
import { EmptyState } from "../shared/empty-state";
import { Skeleton } from "../ui/skeleton";
import { NodeBadges } from "./node-badges";
import { isExternal } from "@repowise-dev/types";
import type { GraphExport, GraphLink, GraphNode } from "@repowise-dev/types/graph";
/**
* The file -> file edge types that mean "this file references that one", the
* TypeScript mirror of the engine's `FILE_DEPENDENCY_EDGE_TYPES`
* (`packages/core/src/repowise/core/ingestion/models.py`).
*
* `co_changes` is the one this deliberately drops, and it is the reason the
* list exists at all: it joins files that were committed together, which is
* history rather than code, and a tree whose per-file list mixed the two would
* report a changelog as an import.
*/
export const CODE_GRAPH_DEPENDENCY_EDGE_TYPES: ReadonlySet<string> = new Set([
"imports",
"type_use",
"framework",
"dynamic_uses",
"dynamic_imports",
"dynamic_url_route",
"reads",
]);
/**
* Whether an edge belongs in a file's import list.
*
* An absent `edge_type` is admitted rather than dropped: the field is optional
* on the wire for back-compat, and an index predating it carries real import
* edges with nothing to classify them. Rendering them unnamed is honest;
* hiding them is not.
*/
function isDependencyEdge(edgeType: string | null | undefined): boolean {
return edgeType === undefined || edgeType === null || CODE_GRAPH_DEPENDENCY_EDGE_TYPES.has(edgeType);
}
/** Short labels for the edge kinds that are not a plain import. */
const EDGE_KIND_LABELS: Record<string, string> = {
type_use: "type reference",
framework: "framework wiring",
dynamic_uses: "dynamic reference",
dynamic_imports: "dynamic import",
dynamic_url_route: "URL route",
reads: "member read",
};
/** One file this file takes names from, with the names themselves. */
export interface CodeGraphImport {
/** The file the names come from; may be an `external:` / `framework:` node. */
target: string;
edge_type: string | null;
/** Sorted and deduped. Empty when the edge carries no names. */
names: string[];
}
/** A file row: the node plus what it imports. */
export interface CodeGraphFile {
node: GraphNode;
imports: CodeGraphImport[];
}
/** One row of the outline: a directory, or a file. */
export interface CodeGraphTreeItem {
/** A directory path, or the file's `node_id`. */
id: string;
/** Basename, for display. Directories keep their own segment. */
name: string;
isDir: boolean;
children: CodeGraphTreeItem[];
/** Files at or below this row (1 for a file row). */
fileCount: number;
/** Present on file rows only. */
file?: CodeGraphFile;
}
/**
* Fold the payload's links into one import list per source file.
*
* Parallel edges are merged rather than listed twice: the engine already
* aggregates `imported_names` onto a single edge per pair, but a payload from
* another producer may not, and two rows for one target reads as two separate
* dependencies. Both endpoints must be nodes in the payload, so the list never
* names a file the tree cannot show. External targets are kept, since
* `external:react` is exactly what a lot of files import.
*/
function collectImports(
nodes: readonly GraphNode[],
links: readonly GraphLink[],
): Map<string, CodeGraphImport[]> {
const nodeIds = new Set(nodes.map((n) => n.node_id));
const bySource = new Map<string, Map<string, { kind: string | null; names: Set<string> }>>();
for (const link of links) {
if (link.source === link.target) continue;
if (!nodeIds.has(link.source) || !nodeIds.has(link.target)) continue;
if (!isDependencyEdge(link.edge_type)) continue;
let targets = bySource.get(link.source);
if (!targets) {
targets = new Map();
bySource.set(link.source, targets);
}
// An edge type is stamped when the edge is created and never rewritten
// (a stronger `imports` edge keeps its kind when a `type_use` pass merges
// into it), so first-wins for the kind is the engine's own answer.
const existing = targets.get(link.target);
if (existing) {
for (const name of link.imported_names ?? []) existing.names.add(name);
} else {
targets.set(link.target, {
kind: link.edge_type ?? null,
names: new Set(link.imported_names ?? []),
});
}
}
const imports = new Map<string, CodeGraphImport[]>();
for (const [source, targets] of bySource) {
imports.set(
source,
[...targets.entries()]
.map(([target, { kind, names }]) => ({
target,
edge_type: kind,
names: [...names].sort(),
}))
.sort((a, b) => a.target.localeCompare(b.target)),
);
}
return imports;
}
/**
* Build the outline from a file-level graph payload.
*
* Directories are derived from the paths, not from the payload: there is no
* directory node to read, and a tree that invented a hierarchy the graph does
* not carry would be describing something other than the files that are there.
*
* `external:` / `framework:` nodes share the node table with real files and are
* not files: they have no path, so they would land at the root as a row nobody
* can open. They are skipped as rows and kept as import targets.
*/
export function buildCodeGraphTree(
nodes: readonly GraphNode[],
links: readonly GraphLink[],
): CodeGraphTreeItem[] {
const imports = collectImports(nodes, links);
const dirs = new Map<string, CodeGraphTreeItem>();
const root: CodeGraphTreeItem[] = [];
function ensureDir(dirPath: string): CodeGraphTreeItem {
const existing = dirs.get(dirPath);
if (existing) return existing;
const parts = dirPath.split("/");
const node: CodeGraphTreeItem = {
id: dirPath,
name: parts[parts.length - 1] ?? dirPath,
isDir: true,
children: [],
fileCount: 0,
};
dirs.set(dirPath, node);
if (parts.length > 1) {
const parent = ensureDir(parts.slice(0, -1).join("/"));
if (!parent.children.some((child) => child.id === dirPath)) parent.children.push(node);
} else {
root.push(node);
}
return node;
}
for (const node of nodes) {
if (isExternal(node.node_id)) continue;
const parts = node.node_id.split("/");
const file: CodeGraphTreeItem = {
id: node.node_id,
name: parts[parts.length - 1] ?? node.node_id,
isDir: false,
children: [],
fileCount: 1,
file: { node, imports: imports.get(node.node_id) ?? [] },
};
if (parts.length > 1) {
ensureDir(parts.slice(0, -1).join("/")).children.push(file);
} else {
root.push(file);
}
}
/** Directories first, then files, each alphabetically, at every level. */
function sortAndCount(items: CodeGraphTreeItem[]): number {
items.sort((a, b) => {
if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
});
let count = 0;
for (const item of items) {
item.fileCount = item.isDir ? sortAndCount(item.children) : 1;
count += item.fileCount;
}
return count;
}
sortAndCount(root);
return root;
}
/** What a file row says about its imports, as figures rather than prose. */
export interface FileImportSummary {
/** Distinct files this file takes names from. */
fileCount: number;
/** Distinct names across those edges. */
nameCount: number;
}
export function summarizeFileImports(imports: readonly CodeGraphImport[]): FileImportSummary {
const names = new Set<string>();
for (const entry of imports) for (const name of entry.names) names.add(name);
return { fileCount: imports.length, nameCount: names.size };
}
/** The one-line count for a file row. Says which half is empty rather than
* printing a figure that describes nothing. */
function importSummaryLabel(summary: FileImportSummary): string {
const { fileCount, nameCount } = summary;
if (fileCount === 0) return "no dependencies";
const files = `${fileCount} ${fileCount === 1 ? "file" : "files"}`;
if (nameCount === 0) return `${files}, no names recorded`;
return `${nameCount} ${nameCount === 1 ? "type" : "types"} from ${files}`;
}
/** Every directory id in the outline, for expand/collapse-all. */
export function collectDirectoryIds(items: readonly CodeGraphTreeItem[]): string[] {
const ids: string[] = [];
const walk = (list: readonly CodeGraphTreeItem[]) => {
for (const item of list) {
if (!item.isDir) continue;
ids.push(item.id);
walk(item.children);
}
};
walk(items);
return ids;
}
// ---------------------------------------------------------------------------
// Rows
// ---------------------------------------------------------------------------
interface RowChrome {
fileHref?: ((path: string) => string) | undefined;
LinkComponent: ElementType;
}
function ImportList({ entry, chrome }: { entry: CodeGraphFile; chrome: RowChrome }) {
if (entry.imports.length === 0) {
return (
<p className="py-1 pl-2 text-xs text-[var(--color-text-tertiary)]">
No dependency edges recorded for this file. Files land in the graph once their
imports are parsed, so an excluded path or an unsupported language leaves this empty.
</p>
);
}
const A = chrome.LinkComponent;
return (
<ul className="mb-1 space-y-1.5 border-l border-[var(--color-border-default)] pl-4">
{entry.imports.map((imp) => {
const kindLabel = imp.edge_type ? EDGE_KIND_LABELS[imp.edge_type] : undefined;
// An external node has no page behind it, so it gets no link: the same
// rule the file page's graph tab follows.
const href = isExternal(imp.target) ? undefined : chrome.fileHref?.(imp.target);
return (
<li key={imp.target}>
<div className="flex flex-wrap items-baseline gap-x-2 gap-y-0.5">
<span
className="font-mono text-[11px] text-[var(--color-text-primary)]"
title={imp.target}
>
{truncatePath(imp.target, 64)}
</span>
{kindLabel && (
<span className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
{kindLabel}
</span>
)}
{href && (
<A
href={href}
className="text-[10px] text-[var(--color-accent-primary)] hover:underline"
aria-label={`Open ${imp.target}`}
>
open <span aria-hidden>→</span>
</A>
)}
</div>
{imp.names.length > 0 ? (
<p className="font-mono text-[11px] leading-relaxed text-[var(--color-text-secondary)] [overflow-wrap:anywhere]">
{imp.names.join(", ")}
</p>
) : (
<p className="text-[11px] text-[var(--color-text-tertiary)]">
The edge records no names, so we know these two files are joined and not what
travelled along it.
</p>
)}
</li>
);
})}
</ul>
);
}
function FileRow({
item,
depth,
expanded,
toggle,
chrome,
}: {
item: CodeGraphTreeItem;
depth: number;
expanded: ReadonlySet<string>;
toggle: (id: string) => void;
chrome: RowChrome;
}) {
const file = item.file;
if (!file) return null;
const isOpen = expanded.has(item.id);
const summary = summarizeFileImports(file.imports);
const href = chrome.fileHref?.(item.id);
const A = chrome.LinkComponent;
const listId = `code-graph-tree-imports-${item.id}`;
return (
<li>
<div
className="flex items-center gap-2 rounded-md pr-2 hover:bg-[var(--color-bg-elevated)]"
style={{ paddingLeft: `${depth * 16 + 8}px` }}
>
<button
type="button"
onClick={() => toggle(item.id)}
aria-expanded={isOpen}
aria-controls={listId}
className="flex min-w-0 flex-1 items-center gap-1.5 rounded-md py-1.5 text-left text-xs text-[var(--color-text-secondary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)]"
>
{isOpen ? (
<ChevronDown className="h-3 w-3 shrink-0 opacity-50" />
) : (
<ChevronRight className="h-3 w-3 shrink-0 opacity-50" />
)}
<FileCode className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)]" />
<span
className="min-w-0 truncate font-mono text-xs text-[var(--color-text-primary)]"
title={item.id}
>
{item.name}
</span>
<NodeBadges
signals={{ isTest: file.node.is_test, isEntryPoint: file.node.is_entry_point }}
only={["isTest", "isEntryPoint"]}
/>
</button>
<span className="shrink-0 font-mono text-[10px] tabular-nums text-[var(--color-text-tertiary)]">
{importSummaryLabel(summary)}
</span>
{href && (
<A
href={href}
className="shrink-0 text-[10px] text-[var(--color-text-tertiary)] hover:text-[var(--color-accent-primary)] hover:underline"
aria-label={`Open ${item.id}`}
>
file <span aria-hidden>→</span>
</A>
)}
</div>
{isOpen && (
<div id={listId} style={{ paddingLeft: `${depth * 16 + 24}px` }} className="pb-1">
<ImportList entry={file} chrome={chrome} />
</div>
)}
</li>
);
}
function DirRow({
item,
depth,
expanded,
toggle,
chrome,
}: {
item: CodeGraphTreeItem;
depth: number;
expanded: ReadonlySet<string>;
toggle: (id: string) => void;
chrome: RowChrome;
}) {
const isOpen = expanded.has(item.id);
return (
<li>
<button
type="button"
onClick={() => toggle(item.id)}
aria-expanded={isOpen}
className={cn(
"flex w-full items-center gap-1.5 rounded-md py-1.5 pr-2 text-left text-xs transition-colors hover:bg-[var(--color-bg-elevated)]",
depth === 0
? "font-semibold text-[var(--color-text-primary)]"
: "text-[var(--color-text-secondary)]",
)}
style={{ paddingLeft: `${depth * 16 + 8}px` }}
>
{isOpen ? (
<ChevronDown className="h-3 w-3 shrink-0 opacity-50" />
) : (
<ChevronRight className="h-3 w-3 shrink-0 opacity-50" />
)}
{isOpen ? (
<FolderOpen className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)] opacity-70" />
) : (
<Folder className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)]" />
)}
<span className="min-w-0 flex-1 truncate font-mono">{item.name}</span>
<span className="shrink-0 font-mono text-[10px] tabular-nums text-[var(--color-text-tertiary)]">
{formatNumber(item.fileCount)} {item.fileCount === 1 ? "file" : "files"}
</span>
</button>
{isOpen && (
<ul>
{item.children.map((child) => (
<TreeRow
key={child.id}
item={child}
depth={depth + 1}
expanded={expanded}
toggle={toggle}
chrome={chrome}
/>
))}
</ul>
)}
</li>
);
}
function TreeRow({
item,
depth,
expanded,
toggle,
chrome,
}: {
item: CodeGraphTreeItem;
depth: number;
expanded: ReadonlySet<string>;
toggle: (id: string) => void;
chrome: RowChrome;
}) {
return item.isDir ? (
<DirRow item={item} depth={depth} expanded={expanded} toggle={toggle} chrome={chrome} />
) : (
<FileRow item={item} depth={depth} expanded={expanded} toggle={toggle} chrome={chrome} />
);
}
// ---------------------------------------------------------------------------
// The tree
// ---------------------------------------------------------------------------
export interface CodeGraphTreeProps {
/** The file-level graph payload. `undefined` while it is still arriving. */
graph: GraphExport | null | undefined;
/** Renders the skeleton instead of the empty state while the first fetch runs. */
isLoading?: boolean | undefined;
/** Builds a file entity page href. Rows render no link when it is omitted. */
fileHref?: ((path: string) => string) | undefined;
/** Router link; defaults to `<a>` so the package stays framework-neutral. */
LinkComponent?: ElementType | undefined;
className?: string | undefined;
}
export function CodeGraphTree({
graph,
isLoading = false,
fileHref,
LinkComponent = "a",
className,
}: CodeGraphTreeProps) {
const tree = useMemo(
() => (graph ? buildCodeGraphTree(graph.nodes, graph.links) : []),
[graph],
);
// Everything starts shut. The top rung on a real repo is dozens of
// directories and thousands of files, and a first screen that is already
// open to depth three is a wall rather than an outline. `Expand all` is one
// click away for the reader who wants the whole shape.
const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => new Set());
const chrome: RowChrome = { fileHref, LinkComponent };
const toggle = (id: string) => {
setExpanded((prev) => {
const next = new Set(prev);
if (next.has(id)) next.delete(id);
else next.add(id);
return next;
});
};
const directoryIds = useMemo(() => collectDirectoryIds(tree), [tree]);
const totalFiles = useMemo(
() => tree.reduce((sum, item) => sum + item.fileCount, 0),
[tree],
);
if (isLoading && !graph) {
return (
<div className={cn("space-y-2", className)} aria-label="Loading the code graph tree">
<Skeleton className="h-4 w-64" />
{Array.from({ length: 10 }).map((_, index) => (
<Skeleton key={index} className="h-7 w-full" />
))}
</div>
);
}
if (tree.length === 0) {
return (
<EmptyState
titleAs="h2"
icon={<ListTree className="h-8 w-8" />}
title="No files to outline"
description="Files land in the graph once their imports are parsed. An empty index, or one whose files are all third-party nodes, leaves this with nothing to draw."
{...(className ? { className } : {})}
/>
);
}
return (
<div className={cn("flex flex-col gap-2", className)}>
<div className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-[var(--color-text-secondary)]">
<p className="min-w-0 flex-1">
<span className="font-medium tabular-nums text-[var(--color-text-primary)]">
{formatNumber(totalFiles)}
</span>{" "}
{totalFiles === 1 ? "file" : "files"} in{" "}
<span className="font-medium tabular-nums text-[var(--color-text-primary)]">
{formatNumber(directoryIds.length)}
</span>{" "}
{directoryIds.length === 1 ? "directory" : "directories"}. Open a file to see the types
it imports and where each one comes from.
</p>
<button
type="button"
onClick={() => setExpanded(new Set(directoryIds))}
className="shrink-0 font-medium text-[var(--color-accent-primary)] hover:underline"
>
Expand all
</button>
<button
type="button"
onClick={() => setExpanded(new Set())}
className="shrink-0 font-medium text-[var(--color-accent-primary)] hover:underline"
>
Collapse all
</button>
</div>
<ul className="space-y-0.5">
{tree.map((item) => (
<TreeRow
key={item.id}
item={item}
depth={0}
expanded={expanded}
toggle={toggle}
chrome={chrome}
/>
))}
</ul>
</div>
);
}