pkgviz 0.7.7 → 0.8.0

package/src/features/graph-view/adapters/inbound/react/useGraphInteractions.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import type { GraphViewEdge, GraphViewElementEvent, GraphViewNode } from '@zora/graph-view';
+import { useMemo, useState } from 'react';
+
+import { applyGraphInteractionPresentation } from '@/features/graph-view/adapters/inbound/react/applyGraphInteractionPresentation';
+import { reduceGraphInteraction } from '@/features/graph-view/domain/reduceGraphInteraction';
+import type { GraphInteractionState } from '@/types/graphInteraction';
+
+/*** Owns leaf interaction state and declarative presentation through public GraphView events. */
+export function useGraphInteractions(
+  nodes: readonly GraphViewNode[],
+  edges: readonly GraphViewEdge[]
+) {
+  const leafIds = useMemo(() => {
+    const parents = new Set(nodes.map(node => node.parentId));
+    return new Set(nodes.filter(node => !parents.has(node.id)).map(node => node.id));
+  }, [nodes]);
+  const [snapshot, setSnapshot] = useState<{
+    readonly leafIds: ReadonlySet<string>;
+    readonly interaction: GraphInteractionState;
+  }>({
+    leafIds,
+    interaction: { hoveredNodeId: null, selectedNodeIds: [] },
+  });
+  if (snapshot.leafIds !== leafIds) {
+    setSnapshot({
+      leafIds,
+      interaction: {
+        hoveredNodeId: null,
+        selectedNodeIds: snapshot.interaction.selectedNodeIds.filter(id => leafIds.has(id)),
+      },
+    });
+  }
+  const presentation = useMemo(
+    () => applyGraphInteractionPresentation(nodes, edges, snapshot.interaction),
+    [nodes, edges, snapshot.interaction]
+  );
+
+  /*** Ignores compound policy and routes only the approved hover/selection events to the reducer. */
+  const handleNodeEvent = (event: GraphViewElementEvent) => {
+    const { id, type } = event;
+    if (!leafIds.has(id) || type === 'press' || type === 'double-press') return;
+    setSnapshot(previous => {
+      const interaction = reduceGraphInteraction(previous.interaction, { id, type });
+      return interaction === previous.interaction ? previous : { leafIds, interaction };
+    });
+  };
+  return { ...presentation, handleNodeEvent };
+}

package/src/features/graph-view/adapters/inbound/react/useGraphProjection.ts

@@ -0,0 +1,71 @@
+'use client';
+import type { ElementsDefinition } from 'cytoscape';
+import { useEffect, useMemo } from 'react';
+
+import { projectVisibleGraph } from '@/features/graph-view/utils/projectVisibleGraph';
+
+/***
+ * Projects graph inputs without changing the explicitly selected package scope.
+ * @performance
+ * Package/depth/vendor projection traverses nodes and aggregates edges. Keep it memoized on its
+ * actual inputs so unrelated UI renders do not repeat that work or replace the visible graph data.
+ * Preserve lifted-edge weights and explicit cycle scopes when optimizing; projectVisibleGraph tests
+ * cover those behaviors. Do not add a second independently maintained projection state.
+ */
+export function useGraphProjection(input: UseGraphProjectionInput): ElementsDefinition | null {
+  const {
+    currentPackage,
+    elements,
+    preservePackageScope,
+    setCurrentPackage,
+    setMaxSubPackageDepth,
+    setSubPackageDepth,
+    showCompoundNodes,
+    showVendorPackages,
+    subPackageDepth,
+  } = input;
+  const projection = useMemo(
+    () =>
+      elements === null
+        ? null
+        : projectVisibleGraph({
+            currentPackage,
+            elements,
+            preservePackageScope,
+            showCompoundNodes,
+            showVendorPackages,
+            subPackageDepth,
+          }),
+    [
+      currentPackage,
+      elements,
+      preservePackageScope,
+      showCompoundNodes,
+      showVendorPackages,
+      subPackageDepth,
+    ]
+  );
+
+  useEffect(() => {
+    if (projection === null) return;
+    setMaxSubPackageDepth(projection.maxSubPackageDepth);
+    if (projection.redirectPackage === null && subPackageDepth > projection.maxSubPackageDepth) {
+      setSubPackageDepth(projection.maxSubPackageDepth);
+    }
+    if (projection.redirectPackage !== null) setCurrentPackage(projection.redirectPackage);
+  }, [projection, setCurrentPackage, setMaxSubPackageDepth, setSubPackageDepth, subPackageDepth]);
+
+  return projection?.redirectPackage === null ? projection.elements : null;
+}
+
+interface UseGraphProjectionInput {
+  readonly currentPackage: string;
+  readonly elements: ElementsDefinition | null;
+  readonly preservePackageScope?: boolean;
+  readonly setCurrentPackage: (path: string) => void;
+  readonly setMaxSubPackageDepth: (depth: number) => void;
+  readonly setSubPackageDepth: (depth: number) => void;
+  readonly showCompoundNodes: boolean;
+  readonly showVendorPackages: boolean;
+  readonly subPackageDepth: number;
+}

package/src/features/graph-view/adapters/inbound/react/useGraphViewport.ts

@@ -0,0 +1,48 @@
+import type { GraphViewController, GraphViewLayoutName } from '@zora/graph-view';
+import { useRef, useState } from 'react';
+
+/***
+ * Mirrors the owner's settled zoom bounds and coordinates intentional layout changes.
+ * @performance
+ * Viewport events only read cached controller values; ordinary zoom must never compact spacing,
+ * measure labels or rerun layout. The explicit Fit button requests the owner's bounded compaction.
+ */
+export function useGraphViewport(layout: GraphViewLayoutName) {
+  const [controller, setController] = useState<GraphViewController | null>(null);
+  const controllerRef = useRef<GraphViewController | null>(null);
+  const [viewport, setViewport] = useState({ zoom: 1, min: 0.5, max: 2 });
+  const previousLayoutRef = useRef(layout);
+
+  /*** Publishes only changed viewport values, including range changes without a zoom event. */
+  const synchronize = (nextController: GraphViewController) => {
+    const { zoom } = nextController.getViewport();
+    const { min, max } = nextController.getZoomRange();
+    setViewport(previous =>
+      previous.zoom === zoom && previous.min === min && previous.max === max
+        ? previous
+        : { zoom, min, max }
+    );
+  };
+
+  /*** Captures the controller before synchronizing the initial viewport. */
+  const handleReady = (nextController: GraphViewController) => {
+    controllerRef.current = nextController;
+    setController(nextController);
+    synchronize(nextController);
+  };
+
+  /*** Reads the controller synchronously, including events before React commits readiness. */
+  const handleViewportChange = () => {
+    if (controllerRef.current !== null) synchronize(controllerRef.current);
+  };
+
+  /*** Fits intentional algorithm changes and refreshes bounds after every settled layout. */
+  const handleLayoutComplete = (nextController: GraphViewController) => {
+    const layoutChanged = previousLayoutRef.current !== layout;
+    previousLayoutRef.current = layout;
+    if (layoutChanged) nextController.fit();
+    synchronize(nextController);
+  };
+
+  return { controller, handleLayoutComplete, handleReady, handleViewportChange, ...viewport };
+}

package/src/features/graph-view/domain/getDependencyHighlightClasses.ts

@@ -0,0 +1,39 @@
+import type { GraphEdge } from '@ankhorage/graph';
+
+/***
+ * Assigns PKGViz highlight/hushed presentation to direct incoming and outgoing dependencies.
+ * @performance Classify edges once per interaction, with set membership instead of per-node scans.
+ * This is product presentation policy; generic graph traversal remains owned by @ankhorage/graph.
+ */
+export function getDependencyHighlightClasses(
+  nodeIds: readonly string[],
+  edges: readonly Pick<GraphEdge, 'source' | 'target'>[],
+  activeNodeIds: ReadonlySet<string>
+) {
+  const outgoing = new Set<string>();
+  const incoming = new Set<string>();
+  const edgeClasses = edges.map(edge => {
+    const fromActive = activeNodeIds.has(edge.source);
+    const toActive = activeNodeIds.has(edge.target);
+    if (fromActive) outgoing.add(edge.target);
+    if (toActive) incoming.add(edge.source);
+    return getClasses(false, fromActive, toActive, activeNodeIds.size > 0);
+  });
+  const nodeClasses = nodeIds.map(id =>
+    getClasses(activeNodeIds.has(id), outgoing.has(id), incoming.has(id), activeNodeIds.size > 0)
+  );
+  return { nodeClasses, edgeClasses };
+}
+
+/*** Keeps dependency direction and active-node emphasis while dimming unrelated elements. */
+function getClasses(active: boolean, outgoing: boolean, incoming: boolean, hasFocus: boolean) {
+  if (!hasFocus) return '';
+  if (!active && !outgoing && !incoming) return 'hushed';
+  return [
+    active ? 'highlight' : '',
+    outgoing ? 'highlight-outgoer' : '',
+    incoming ? 'highlight-incomer' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+}

package/src/features/graph-view/domain/reduceGraphInteraction.ts

@@ -0,0 +1,23 @@
+import type { GraphInteractionEvent, GraphInteractionState } from '@/types/graphInteraction';
+
+/*** Tracks leaf hover separately from selection so pointer exit restores the selected neighborhood. */
+export function reduceGraphInteraction(
+  state: GraphInteractionState,
+  event: GraphInteractionEvent
+): GraphInteractionState {
+  if (event.type === 'pointer-enter') {
+    return state.hoveredNodeId === event.id ? state : { ...state, hoveredNodeId: event.id };
+  }
+  if (event.type === 'pointer-leave') {
+    return state.hoveredNodeId === event.id ? { ...state, hoveredNodeId: null } : state;
+  }
+  const selected = state.selectedNodeIds.includes(event.id);
+  if ((event.type === 'select') === selected) return state;
+  return {
+    ...state,
+    selectedNodeIds:
+      event.type === 'select'
+        ? [...state.selectedNodeIds, event.id]
+        : state.selectedNodeIds.filter(id => id !== event.id),
+  };
+}

package/src/features/graph-view/utils/createCompoundOpacityIndex.ts

@@ -0,0 +1,38 @@
+/***
+ * Prepares paint-only depth steps with a bounded cumulative tint for nested compound surfaces.
+ * @performance Memoize ancestry once per projection; never traverse parents in style callbacks.
+ */
+export function createCompoundOpacityIndex(
+  parents: ReadonlyMap<string, string>,
+  detached: ReadonlySet<string>
+): ReadonlyMap<string, number> {
+  const depths = new Map<string, number>();
+  const visiting = new Set<string>();
+
+  /*** Resolves effective visual depth, accounting for detached dependency endpoints. */
+  function depth(id: string): number {
+    const cached = depths.get(id);
+    if (cached !== undefined) return cached;
+    if (visiting.has(id)) return 0;
+    visiting.add(id);
+    const parent = detached.has(id) ? undefined : parents.get(id);
+    const result = parent === undefined ? 0 : depth(parent) + 1;
+    visiting.delete(id);
+    depths.set(id, result);
+    return result;
+  }
+
+  return new Map(
+    [...new Set([...parents.keys(), ...parents.values()])].map(id => {
+      const level = depth(id);
+      const target = cumulativeTint(level);
+      const previous = level === 0 ? 0 : cumulativeTint(level - 1);
+      return [id, (target - previous) / (1 - previous)];
+    })
+  );
+}
+
+/*** Approaches an 18% cumulative tint without letting deep nesting become an opaque blue slab. */
+function cumulativeTint(depth: number): number {
+  return 0.04 + (0.14 * depth) / (depth + 3);
+}

package/src/features/graph-view/utils/projectVisibleGraph.ts

@@ -0,0 +1,94 @@
+import type { ElementsDefinition } from 'cytoscape';
+
+import { removeEmptyStructuralNodes } from '@/features/graph-view/utils/removeEmptyStructuralNodes';
+import { filterByPackagePrefix } from '@/utils/filter/filterByPackagePrefix';
+import { filterEmptyPackages } from '@/utils/filter/filterEmptyPackages';
+import { filterSubPackagesByDepth, getMaxDepth } from '@/utils/filter/filterSubPackagesFromDepth';
+import { filterVendorPackages } from '@/utils/filter/filterVendorPackages';
+import { toggleCompoundNodes } from '@/utils/filter/toggleCompoundNodes';
+
+/*** Projects the complete dependency graph into the explicitly selected package/depth/filter view. */
+export function projectVisibleGraph(input: ProjectVisibleGraphInput): ProjectVisibleGraphResult {
+  const compoundFiltered = toggleCompoundNodes(
+    input.elements,
+    input.showCompoundNodes,
+    input.currentPackage
+  );
+  const packageFiltered = filterByPackagePrefix(
+    compoundFiltered,
+    input.currentPackage.replace(/\//g, '.')
+  );
+  const depthFiltered = filterSubPackagesByDepth(packageFiltered, true, input.subPackageDepth);
+  const visible = input.showVendorPackages ? depthFiltered : filterVendorPackages(depthFiltered);
+
+  return {
+    elements: labelVisibleNodes(
+      input.showCompoundNodes ? visible : removeEmptyStructuralNodes(visible),
+      input.currentPackage
+    ),
+    maxSubPackageDepth: Math.max(
+      1,
+      getMaxDepth(
+        input.showVendorPackages ? packageFiltered : filterVendorPackages(packageFiltered)
+      )
+    ),
+    redirectPackage: resolveRedirectPackage(input),
+  };
+}
+
+interface ProjectVisibleGraphInput {
+  readonly currentPackage: string;
+  readonly elements: ElementsDefinition;
+  readonly preservePackageScope?: boolean;
+  readonly showCompoundNodes: boolean;
+  readonly showVendorPackages: boolean;
+  readonly subPackageDepth: number;
+}
+
+interface ProjectVisibleGraphResult {
+  readonly elements: ElementsDefinition;
+  readonly maxSubPackageDepth: number;
+  readonly redirectPackage: string | null;
+}
+
+/***
+ * Skips empty package levels only when no explicit cycle scope owns the projection.
+ * @performance
+ * An active cycle can require an ancestor package as a visible node. Redirecting into that package
+ * hides it again and causes an endless focus/redirect loop, repeatedly remounting the renderer.
+ */
+function resolveRedirectPackage(input: ProjectVisibleGraphInput): string | null {
+  const currentPackage = input.currentPackage.replaceAll('/', '.');
+  if (input.preservePackageScope) return null;
+
+  const nextPackage = filterEmptyPackages(currentPackage, input.elements);
+  return nextPackage === currentPackage ? null : nextPackage;
+}
+
+/*** Adds package-relative display labels without changing graph ids. */
+function labelVisibleNodes(
+  elements: ElementsDefinition,
+  currentPackage: string
+): ElementsDefinition {
+  const normalizedPackage = currentPackage.replaceAll('/', '.');
+
+  return {
+    nodes: elements.nodes.map(node => ({
+      group: 'nodes',
+      classes: node.classes ?? '',
+      data: {
+        ...node.data,
+        label: getRelativeNodeLabel(String(node.data.id ?? ''), normalizedPackage),
+      },
+    })),
+    edges: elements.edges,
+  };
+}
+
+/*** Resolves a readable label for the active package itself and for its descendants. */
+function getRelativeNodeLabel(id: string, currentPackage: string): string {
+  if (!currentPackage) return id;
+  if (id === currentPackage) return id.split('.').at(-1) ?? id;
+  const descendantPrefix = currentPackage + '.';
+  return id.startsWith(descendantPrefix) ? id.slice(descendantPrefix.length) : id;
+}

package/src/features/graph-view/utils/readNodeDefinitionId.ts

@@ -0,0 +1,7 @@
+import type { NodeDefinition } from 'cytoscape';
+
+/*** Reads a Cytoscape node-definition id through a typed graph-view boundary. */
+export function readNodeDefinitionId(node: NodeDefinition): string | null {
+  const id: unknown = node.data.id;
+  return typeof id === 'string' ? id : null;
+}

package/src/features/graph-view/utils/removeEmptyStructuralNodes.ts

@@ -0,0 +1,27 @@
+import type { ElementsDefinition } from 'cytoscape';
+
+import { isIntrinsicGraphNode } from '@/utils/filter/isIntrinsicGraphNode';
+
+/***
+ * Omits relationship-free containers in flat views, but preserves actual isolated leaf packages.
+ * @performance Index connected endpoints and ancestors once instead of scanning the graph per node.
+ */
+export function removeEmptyStructuralNodes(elements: ElementsDefinition): ElementsDefinition {
+  const connected = new Set(elements.edges.flatMap(edge => [edge.data.source, edge.data.target]));
+  const ancestors = new Set<string>();
+  for (const node of elements.nodes.filter(isIntrinsicGraphNode)) {
+    const segments = String(node.data.id ?? '').split('.');
+    for (let length = 1; length < segments.length; length += 1) {
+      ancestors.add(segments.slice(0, length).join('.'));
+    }
+  }
+  return {
+    nodes: elements.nodes.filter(
+      node =>
+        !isIntrinsicGraphNode(node) ||
+        !ancestors.has(String(node.data.id)) ||
+        connected.has(String(node.data.id))
+    ),
+    edges: elements.edges,
+  };
+}

package/src/features/project-analysis/adapters/outbound/filesystem/readProjectSnapshotAsync.ts

@@ -0,0 +1,12 @@
+import { buildGraph } from '@/app/utils/buildGraph';
+import { getParsedFileStructure } from '@/app/utils/getParsedFileStructure';
+import { inspectParserLanguageAsync } from '@/app/utils/inspectParserLanguageAsync';
+import type { ProjectSnapshot } from '@/types/projectAnalysis';
+
+/*** Reads one project's language and source files and constructs its shared weighted graph. */
+export async function readProjectSnapshotAsync(projectPath: string): Promise<ProjectSnapshot> {
+  const timeStart = Date.now();
+  const language = await inspectParserLanguageAsync(projectPath);
+  const files = await getParsedFileStructure(language.language, projectPath);
+  return { files, graph: buildGraph(files), language, projectPath, timeStart };
+}

package/src/features/project-analysis/application/use-cases/createProjectSnapshotReader.ts

@@ -0,0 +1,29 @@
+import type { ProjectSnapshot } from '@/types/projectAnalysis';
+
+/***
+ * Shares only in-flight analysis of the same normalized project path within one server process.
+ * @performance
+ * Graph, tree and audit must share the parsed files and graph, not independently scan the project.
+ * Entries are removed after success or failure so later loads observe source changes and can retry.
+ */
+export function createProjectSnapshotReader(source: ProjectSnapshotSource) {
+  const pending = new Map<string, Promise<ProjectSnapshot>>();
+
+  /*** Joins the current project analysis or starts a fresh snapshot through the source port. */
+  function readAsync(projectPath: string): Promise<ProjectSnapshot> {
+    const current = pending.get(projectPath);
+    if (current !== undefined) return current;
+
+    const next = Promise.resolve()
+      .then(() => source.readAsync(projectPath))
+      .finally(() => pending.delete(projectPath));
+    pending.set(projectPath, next);
+    return next;
+  }
+
+  return { readAsync };
+}
+
+interface ProjectSnapshotSource {
+  readonly readAsync: (projectPath: string) => Promise<ProjectSnapshot>;
+}

package/src/features/project-analysis/composition/loadProjectOverviewAsync.ts

@@ -0,0 +1,14 @@
+import { createAuditFromSnapshot } from '@/features/audit/application/use-cases/createAuditFromSnapshot';
+import { loadProjectSnapshotAsync } from '@/features/project-analysis/composition/loadProjectSnapshotAsync';
+import { buildProjectTree } from '@/features/project-tree/application/use-cases/buildProjectTree';
+import type { ProjectOverview } from '@/types/projectAnalysis';
+
+/*** Derives graph, tree and audit evaluation from one freshly shared project snapshot. */
+export async function loadProjectOverviewAsync(projectPath: string): Promise<ProjectOverview> {
+  const snapshot = await loadProjectSnapshotAsync(projectPath);
+  return {
+    graph: snapshot.graph,
+    tree: buildProjectTree(snapshot.files),
+    evaluation: createAuditFromSnapshot(snapshot).evaluation,
+  };
+}

package/src/features/project-analysis/composition/loadProjectSnapshotAsync.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'node:path';
+
+import { readProjectSnapshotAsync } from '@/features/project-analysis/adapters/outbound/filesystem/readProjectSnapshotAsync';
+import { createProjectSnapshotReader } from '@/features/project-analysis/application/use-cases/createProjectSnapshotReader';
+import type { ProjectSnapshot } from '@/types/projectAnalysis';
+
+/*** Wires the filesystem reader to process-local in-flight sharing using normalized project paths. */
+export function loadProjectSnapshotAsync(projectPath: string): Promise<ProjectSnapshot> {
+  return reader.readAsync(resolve(projectPath));
+}
+
+const reader = createProjectSnapshotReader({ readAsync: readProjectSnapshotAsync });

package/src/features/project-tree/adapters/inbound/react/ProjectTreePanel.tsx

@@ -0,0 +1,52 @@
+'use client';
+import { type TreeItemNode, TreeView } from '@zora/tree-view';
+import { FileCode2Icon, FolderIcon } from 'lucide-react';
+import React from 'react';
+
+import { useProjectTreeExpansion } from '@/features/project-tree/adapters/inbound/react/useProjectTreeExpansion';
+import { findProjectTreeNode } from '@/features/project-tree/utils/findProjectTreeNode';
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Adapts PKGViz's serializable project tree to the generated ZORA browser TreeView. */
+export function ProjectTreePanel({ nodes, onSelect, selectedId }: ProjectTreePanelProps) {
+  const treeNodes = React.useMemo(() => nodes.map(toTreeItemNode), [nodes]);
+  const expansion = useProjectTreeExpansion(nodes, selectedId);
+
+  return (
+    <div className="px-2 pt-2 text-xs">
+      <TreeView
+        ariaLabel="Project tree"
+        expansionIndicator="folder"
+        expandedIds={expansion.expandedIds}
+        nodes={treeNodes}
+        selectedId={selectedId ?? undefined}
+        onExpandedChange={expansion.onExpandedChange}
+        onSelect={id => {
+          const node = findProjectTreeNode(nodes, id);
+          if (node) onSelect(node);
+        }}
+      />
+    </div>
+  );
+}
+
+/*** Maps a portable project-tree node into the ZORA TreeView presentation contract. */
+function toTreeItemNode(node: ProjectTreeNode): TreeItemNode {
+  return {
+    id: node.id,
+    label: node.label,
+    icon:
+      node.kind === 'directory' ? (
+        <FolderIcon aria-hidden size={14} />
+      ) : (
+        <FileCode2Icon aria-hidden size={14} />
+      ),
+    ...(node.children ? { children: node.children.map(toTreeItemNode) } : {}),
+  };
+}
+
+interface ProjectTreePanelProps {
+  readonly nodes: readonly ProjectTreeNode[];
+  readonly onSelect: (node: ProjectTreeNode) => void;
+  readonly selectedId: string | null;
+}

package/src/features/project-tree/adapters/inbound/react/useProjectTreeExpansion.ts

@@ -0,0 +1,46 @@
+import { useState } from 'react';
+
+import { findProjectTreeNode } from '@/features/project-tree/utils/findProjectTreeNode';
+import { getProjectTreeAncestorIds } from '@/features/project-tree/utils/getProjectTreeAncestorIds';
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Opens a navigated folder once while preserving subsequent manual collapse and expansion. */
+export function useProjectTreeExpansion(
+  nodes: readonly ProjectTreeNode[],
+  selectedId: string | null
+) {
+  const [state, setState] = useState(() => ({
+    nodes,
+    selectedId,
+    ids: revealSelection(
+      nodes,
+      selectedId,
+      nodes.filter(node => node.kind === 'directory').map(node => node.id)
+    ),
+  }));
+  if (state.nodes !== nodes || state.selectedId !== selectedId) {
+    setState({ nodes, selectedId, ids: revealSelection(nodes, selectedId, state.ids) });
+  }
+
+  return {
+    expandedIds: state.ids,
+    onExpandedChange: (ids: readonly string[]) => setState({ nodes, selectedId, ids }),
+  };
+}
+
+/*** Adds ancestors and the selected directory without turning files into expandable items. */
+function revealSelection(
+  nodes: readonly ProjectTreeNode[],
+  selectedId: string | null,
+  ids: readonly string[]
+) {
+  if (selectedId === null) return ids;
+  const selected = findProjectTreeNode(nodes, selectedId);
+  return [
+    ...new Set([
+      ...ids,
+      ...getProjectTreeAncestorIds(nodes, selectedId),
+      ...(selected?.kind === 'directory' ? [selectedId] : []),
+    ]),
+  ];
+}

package/src/features/project-tree/application/use-cases/buildProjectTree.ts

@@ -0,0 +1,61 @@
+import type { ParsedDirectory, ParsedFile } from '@/shared/types';
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Converts parsed-project data into the serializable hierarchy consumed by the sidebar. */
+export function buildProjectTree(
+  directory: ParsedDirectory,
+  parentPath = ''
+): readonly ProjectTreeNode[] {
+  return Object.entries(directory)
+    .sort(compareEntries)
+    .map(([name, value]) => {
+      const itemPath = parentPath ? `${parentPath}/${name}` : name;
+      if (isParsedFile(value)) {
+        return {
+          graphPackage: value.package,
+          id: `file:${itemPath}`,
+          kind: 'file' as const,
+          label: name,
+        };
+      }
+
+      const children = buildProjectTree(value, itemPath);
+      return {
+        children,
+        graphPackage: getCommonGraphPackage(children),
+        id: `directory:${itemPath}`,
+        kind: 'directory' as const,
+        label: name,
+      };
+    });
+}
+
+/*** Sorts folders before files while keeping each group alphabetic. */
+function compareEntries(
+  [leftName, left]: [string, ParsedDirectory | ParsedFile],
+  [rightName, right]: [string, ParsedDirectory | ParsedFile]
+) {
+  const kindDelta = Number(isParsedFile(left)) - Number(isParsedFile(right));
+  return kindDelta || leftName.localeCompare(rightName);
+}
+
+/*** Derives the graph package represented by a filesystem directory from its descendants. */
+function getCommonGraphPackage(children: readonly ProjectTreeNode[]): string {
+  const packages = children
+    .map(child => child.graphPackage)
+    .filter(packageName => packageName.length);
+  const [firstPackage, ...remainingPackages] = packages;
+  if (!firstPackage) return '';
+
+  const firstSegments = firstPackage.split('.');
+  const mismatchIndex = firstSegments.findIndex((segment, index) =>
+    remainingPackages.some(packageName => packageName.split('.').at(index) !== segment)
+  );
+  const commonLength = mismatchIndex === -1 ? firstSegments.length : mismatchIndex;
+  return firstSegments.slice(0, commonLength).join('.');
+}
+
+/*** Distinguishes parsed files from recursive directory records without relying on class names. */
+function isParsedFile(value: ParsedDirectory | ParsedFile): value is ParsedFile {
+  return 'path' in value && typeof value.path === 'string' && 'package' in value;
+}

package/src/features/project-tree/application/use-cases/resolveProjectTreeNavigation.ts

@@ -0,0 +1,13 @@
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Resolves tree selection using the same package-descendant rule as graph double-press navigation. */
+export function resolveProjectTreeNavigation(
+  node: ProjectTreeNode,
+  packageIds: readonly string[],
+  currentPackage: string
+): string {
+  const packageId = node.graphPackage.replaceAll('/', '.').replace(/^\.+|\.+$/g, '');
+  if (!packageId) return currentPackage;
+  const descendantPrefix = packageId + '.';
+  return packageIds.some(id => id.startsWith(descendantPrefix)) ? packageId : currentPackage;
+}

package/src/features/project-tree/utils/findProjectTreeNode.ts

@@ -0,0 +1,14 @@
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Finds one project-tree node recursively by its stable generated id. */
+export function findProjectTreeNode(
+  nodes: readonly ProjectTreeNode[],
+  id: string
+): ProjectTreeNode | null {
+  for (const node of nodes) {
+    if (node.id === id) return node;
+    const nested = node.children ? findProjectTreeNode(node.children, id) : null;
+    if (nested) return nested;
+  }
+  return null;
+}