pkgviz 0.7.7 → 0.8.1

package/src/screens/home/Home.tsx

@@ -1,48 +1,96 @@
 'use client';
-import type { ElementsDefinition } from 'cytoscape';
+import { useState } from 'react';
 
-import { useEffect, useState } from 'react';
-import { getGraphAction } from '@/app/actions/graph.actions';
 import Breadcrumb from '@/components/Breadcrumb';
 import Header from '@/components/Header';
-import Loader from '@/components/Loader';
-import Settings from '@/components/Settings';
-import { Cytoscape } from '@/components/Cytoscape';
+import ProjectLoadError from '@/components/ProjectLoadError';
 import { SettingsProvider } from '@/contexts/SettingsContext';
+import { useCycleSelection } from '@/features/audit/adapters/inbound/react/useCycleSelection';
+import { resolveProjectTreeNavigation } from '@/features/project-tree/application/use-cases/resolveProjectTreeNavigation';
+import { findProjectTreeNodeByGraphPackage } from '@/features/project-tree/utils/findProjectTreeNodeByGraphPackage';
+import { HomeGraph } from '@/screens/home/HomeGraph';
+import { HomeSidebar } from '@/screens/home/HomeSidebar';
+import type { Audit } from '@/types/audit';
+import type { CycleInspection } from '@/types/auditVisualization';
+import type { ProjectOverview } from '@/types/projectAnalysis';
+import type { ProjectAnalysisActionResult } from '@/types/projectAnalysisActionResult';
+import type { ProjectTreeNode } from '@/types/projectTree';
 
-export default function HomeScreen() {
+/*** Renders the PKGViz home screen and composes project navigation, diagnostics, and the graph. */
+export default function HomeScreen({ project }: HomeScreenProps) {
   const [currentPackage, setCurrentPackage] = useState<string>('');
-  const [packageGraph, setPackageGraph] = useState<ElementsDefinition | null>(null);
+  const packageGraph = project.ok ? project.value.graph : null;
+  const projectTree = project.ok ? project.value.tree : [];
+  const [selectedTreeId, setSelectedTreeId] = useState<string | null>(null);
+  const auditEvaluation = project.ok ? project.value.evaluation : null;
+  const projectError = project.ok ? null : project.error;
+  const cycleSelection = useCycleSelection(auditEvaluation?.cyclicPackages ?? EMPTY_CYCLES);
+  const [cycleInspection, setCycleInspection] = useState<CycleInspection | null>(null);
 
-  useEffect(() => {
-    if (!packageGraph) {
-      getGraphAction().then(setPackageGraph);
-    }
-  }, [packageGraph]);
+  /*** Navigates graph scope and mirrors the matching package selection in the project tree. */
+  const navigateToPackage = (path: string) => {
+    const packageName = normalizeGraphPackage(path);
+    const matchingTreeNode = findProjectTreeNodeByGraphPackage(projectTree, packageName);
+    setCurrentPackage(packageName);
+    setSelectedTreeId(matchingTreeNode?.id ?? null);
+  };
+
+  /*** Navigates only into packages with graph descendants; selecting a leaf keeps the current view. */
+  const selectProjectTreeNode = (node: ProjectTreeNode) => {
+    setSelectedTreeId(node.id);
+    setCurrentPackage(
+      resolveProjectTreeNavigation(
+        node,
+        packageGraph?.nodes.map(candidate => String(candidate.data.id ?? '')) ?? [],
+        currentPackage
+      )
+    );
+  };
 
   return (
     <>
       <Header title="nav.packages">
-        <Breadcrumb
-          path={currentPackage.replace(/\./g, '/')}
-          onNavigate={(path: string) => setCurrentPackage(path.replace(/\//g, '.'))}
-        />
+        <Breadcrumb path={currentPackage.replace(/\./g, '/')} onNavigate={navigateToPackage} />
       </Header>
-
       <SettingsProvider>
-        <main data-testid="main" className="flex flex-1 flex-row dark:bg-[#171717]">
-          <Settings />
-          {packageGraph ? (
-            <Cytoscape
+        <main
+          data-testid="main"
+          className="flex min-h-0 min-w-0 flex-1 flex-row overflow-hidden dark:bg-[#171717]"
+        >
+          <HomeSidebar
+            evaluation={auditEvaluation}
+            projectTree={projectTree}
+            selectedTreeId={selectedTreeId}
+            onProjectTreeSelect={selectProjectTreeNode}
+            cycleSelection={cycleSelection}
+            inspectedCycleId={cycleInspection?.id ?? null}
+            onCycleInspectionChange={setCycleInspection}
+          />
+          {projectError ? (
+            <ProjectLoadError message={projectError} />
+          ) : (
+            <HomeGraph
               currentPackage={currentPackage}
-              setCurrentPackage={setCurrentPackage}
+              cycleHighlights={cycleSelection.highlights}
+              cycleInspection={cycleInspection}
               packageGraph={packageGraph}
+              setCurrentPackage={navigateToPackage}
+              onCloseInspection={() => setCycleInspection(null)}
             />
-          ) : (
-            <Loader />
           )}
         </main>
       </SettingsProvider>
     </>
   );
 }
+
+const EMPTY_CYCLES: NonNullable<Audit['evaluation']>['cyclicPackages'] = [];
+
+interface HomeScreenProps {
+  readonly project: ProjectAnalysisActionResult<ProjectOverview>;
+}
+
+/*** Normalizes graph navigation paths to the package-id representation used by Cytoscape. */
+function normalizeGraphPackage(path: string): string {
+  return path.replaceAll('/', '.').replace(/^\.+|\.+$/g, '');
+}

package/src/screens/home/HomeGraph.tsx

@@ -0,0 +1,43 @@
+'use client';
+import type { ElementsDefinition } from 'cytoscape';
+import React from 'react';
+
+import Loader from '@/components/Loader';
+import { CycleInspector } from '@/features/audit/adapters/inbound/react/CycleInspector';
+import { DependencyGraphView } from '@/features/graph-view/adapters/inbound/react/DependencyGraphView';
+import type { CycleHighlight, CycleInspection } from '@/types/auditVisualization';
+
+/*** Renders the graph surface together with its optional cycle inspector overlay. */
+export function HomeGraph({
+  currentPackage,
+  cycleHighlights,
+  cycleInspection,
+  packageGraph,
+  setCurrentPackage,
+  onCloseInspection,
+}: HomeGraphProps) {
+  if (!packageGraph) return <Loader />;
+
+  return (
+    <DependencyGraphView
+      currentPackage={currentPackage}
+      setCurrentPackage={setCurrentPackage}
+      packageGraph={packageGraph}
+      cycleHighlights={cycleHighlights}
+      overlay={
+        cycleInspection === null ? null : (
+          <CycleInspector inspection={cycleInspection} onClose={onCloseInspection} />
+        )
+      }
+    />
+  );
+}
+
+interface HomeGraphProps {
+  readonly currentPackage: string;
+  readonly cycleHighlights: readonly CycleHighlight[];
+  readonly cycleInspection: CycleInspection | null;
+  readonly packageGraph: ElementsDefinition | null;
+  readonly setCurrentPackage: (path: string) => void;
+  readonly onCloseInspection: () => void;
+}

package/src/screens/home/HomeSidebar.tsx

@@ -0,0 +1,129 @@
+'use client';
+import React from 'react';
+
+import { ExportPanel } from '@/components/ExportPanel';
+import { SettingsPanel } from '@/components/SettingsPanel';
+import { Sidebar } from '@/components/sidebar/Sidebar';
+import { SidebarTabs } from '@/components/sidebar/SidebarTabs';
+import { AuditRulePanel } from '@/features/audit/adapters/inbound/react/AuditRulePanel';
+import { ProjectTreePanel } from '@/features/project-tree/adapters/inbound/react/ProjectTreePanel';
+import { t } from '@/i18n/i18n';
+import type { Audit } from '@/types/audit';
+import type { CycleInspection, CycleSelection } from '@/types/auditVisualization';
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Composes Tree, Rules, and Export above persistent graph settings. */
+export function HomeSidebar(props: HomeSidebarProps) {
+  const [activeTool, setActiveTool] = React.useState<string | null>('tree');
+
+  /*** Closes the evidence panel without changing the user's cycle visualization choices. */
+  const selectTool = (value: string) => {
+    if (activeTool === 'rules' && value !== 'rules') {
+      props.onCycleInspectionChange(null);
+    }
+    setActiveTool(value);
+  };
+
+  return (
+    <Sidebar>
+      <SidebarToolTabs
+        activeTool={activeTool}
+        evaluation={props.evaluation}
+        cycleSelection={props.cycleSelection}
+        inspectedCycleId={props.inspectedCycleId}
+        onCycleInspectionChange={props.onCycleInspectionChange}
+        onProjectTreeSelect={props.onProjectTreeSelect}
+        onValueChange={selectTool}
+        projectTree={props.projectTree}
+        selectedTreeId={props.selectedTreeId}
+      />
+      <div className="shrink-0">
+        <SettingsPanel />
+      </div>
+    </Sidebar>
+  );
+}
+
+/*** Renders project-tree navigation together with secondary Rules and Export tools. */
+function SidebarToolTabs({
+  activeTool,
+  evaluation,
+  cycleSelection,
+  inspectedCycleId,
+  onCycleInspectionChange,
+  onProjectTreeSelect,
+  onValueChange,
+  projectTree,
+  selectedTreeId,
+}: SidebarToolTabsProps) {
+  const violatedRuleCount = evaluation?.rules.filter(rule => rule.status === 'failed').length ?? 0;
+  const findingCount =
+    evaluation?.rules
+      .filter(rule => rule.status === 'failed')
+      .reduce(
+        (count, rule) =>
+          count +
+          (rule.id === 'cyclic-dependencies'
+            ? evaluation.cyclicPackages.length
+            : rule.details.length),
+        0
+      ) ?? 0;
+
+  return (
+    <SidebarTabs
+      ariaLabel={t('sidebar.tools')}
+      value={activeTool}
+      onValueChange={onValueChange}
+      tabs={[
+        {
+          id: 'tree',
+          label: t('settings.tree'),
+          content: (
+            <ProjectTreePanel
+              nodes={projectTree}
+              selectedId={selectedTreeId}
+              onSelect={onProjectTreeSelect}
+            />
+          ),
+        },
+        {
+          id: 'rules',
+          label: `${t('settings.rules')} · ${findingCount} ${t('audit.findings')}`,
+          disabled: violatedRuleCount === 0,
+          content:
+            evaluation === null ? null : (
+              <AuditRulePanel
+                evaluation={evaluation}
+                cycleSelection={cycleSelection}
+                inspectedCycleId={inspectedCycleId}
+                onCycleInspectionChange={onCycleInspectionChange}
+              />
+            ),
+        },
+        { id: 'export', label: t('settings.export'), content: <ExportPanel /> },
+      ]}
+    />
+  );
+}
+
+interface HomeSidebarProps {
+  readonly inspectedCycleId: string | null;
+  readonly evaluation: Audit['evaluation'] | null;
+  readonly projectTree: readonly ProjectTreeNode[];
+  readonly selectedTreeId: string | null;
+  readonly onProjectTreeSelect: (node: ProjectTreeNode) => void;
+  readonly cycleSelection: CycleSelection;
+  readonly onCycleInspectionChange: (inspection: CycleInspection | null) => void;
+}
+
+interface SidebarToolTabsProps {
+  readonly inspectedCycleId: string | null;
+  readonly activeTool: string | null;
+  readonly evaluation: Audit['evaluation'] | null;
+  readonly cycleSelection: CycleSelection;
+  readonly onCycleInspectionChange: (inspection: CycleInspection | null) => void;
+  readonly onProjectTreeSelect: (node: ProjectTreeNode) => void;
+  readonly onValueChange: (value: string) => void;
+  readonly projectTree: readonly ProjectTreeNode[];
+  readonly selectedTreeId: string | null;
+}

package/src/shared/types/index.ts

@@ -15,15 +15,6 @@ export enum Language {
   Unknown = 'unknown',
 }
 
-/**
- * Language Detection Result
- */
-export interface LanguageDetectionResult {
-  language: Language;
-  confidence: number;
-  indicators: string[];
-}
-
 //////////////////////////////////////////////////////////////////////////
 // Parser Types
 

package/src/shared/utils/getProjectName.ts

@@ -1,3 +1,6 @@
 import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+import { toPosix } from '@/shared/utils/toPosix';
 
-export const getProjectName = () => parseProjectPath().split('/').pop() || '{unknown}';
+/*** Returns the project name for an explicit or configured project path. */
+export const getProjectName = (projectPath: string = parseProjectPath()) =>
+  toPosix(projectPath).split('/').pop() || '{unknown}';

package/src/shared/utils/parseProjectPath.ts

@@ -1,5 +1,6 @@
 import { toPosix } from '@/shared/utils/toPosix';
 
+/*** Returns the configured project path in POSIX form. */
 export const parseProjectPath = () => {
   const projectPath = process.env.NEXT_PUBLIC_PROJECT_PATH;
   if (!projectPath) throw new Error('Missing ENV: NEXT_PUBLIC_PROJECT_PATH');

package/src/shared/utils/toPosix.ts

@@ -1,4 +1,4 @@
-/**
+/***
  * Converts Windows-style backslashes in a file path to POSIX-style forward slashes.
  * @example 'C:\\Users\\User\\Documents\\Project' => 'C:/Users/User/Documents/Project'
  */

package/src/types/audit.ts

@@ -0,0 +1,76 @@
+import type { ParsedDirectory } from '@/shared/types';
+import type { ParserSelection } from '@/types/parserSelection';
+
+type AuditRuleMode = 'audit' | 'block' | 'off';
+type AuditRulePolicy = 'advisory' | 'blocking';
+type AuditRuleStatus = 'failed' | 'passed';
+
+export interface AuditRuleConfiguration {
+  readonly id: string;
+  readonly mode: AuditRuleMode;
+}
+
+export interface AuditConfiguration {
+  readonly failOnRuleViolation: boolean;
+  readonly rules: readonly AuditRuleConfiguration[];
+}
+
+export interface ResolveAuditConfigurationInput {
+  readonly failOnRuleViolation?: boolean;
+  readonly rules?: readonly AuditRuleConfiguration[];
+}
+
+export interface ImportEvidence {
+  readonly filePath: string;
+  readonly fileClass: string;
+  readonly importName: string;
+  readonly isIntrinsic?: boolean;
+}
+
+export interface CycleEdgeEvidence {
+  readonly from: string;
+  readonly to: string;
+  readonly via: readonly ImportEvidence[];
+}
+
+export interface PackageCycleDetail {
+  readonly packages: readonly string[];
+  readonly edges: readonly CycleEdgeEvidence[];
+}
+
+export interface AuditRuleResult<TEvidence = unknown> {
+  readonly id: string;
+  readonly status: AuditRuleStatus;
+  readonly policy: AuditRulePolicy;
+  readonly message: string;
+  readonly details: readonly string[];
+  readonly evidence: TEvidence;
+}
+
+export interface CyclicDependenciesEvidence {
+  readonly cycles: readonly PackageCycleDetail[];
+}
+
+interface AuditEvaluation {
+  readonly cyclicPackages: readonly PackageCycleDetail[];
+  readonly rules: readonly AuditRuleResult[];
+}
+
+interface AuditMeta {
+  readonly timeEnd: number;
+  readonly timeStart: number;
+  readonly language: ParserSelection;
+  readonly projectName: string;
+}
+
+export interface Audit {
+  readonly configuration: AuditConfiguration;
+  readonly evaluation: AuditEvaluation;
+  readonly meta: AuditMeta;
+  readonly files: ParsedDirectory;
+}
+
+export interface EvaluateAuditRulesInput {
+  readonly configuration: AuditConfiguration;
+  readonly cyclicPackages: readonly PackageCycleDetail[];
+}

package/src/types/auditVisualization.ts

@@ -0,0 +1,22 @@
+import type { PackageCycleDetail } from '@/types/audit';
+
+export interface CycleHighlight {
+  readonly id: string;
+  readonly color: string;
+  readonly cycle: PackageCycleDetail;
+}
+
+export interface CycleInspection extends CycleHighlight {
+  readonly label: string;
+}
+
+export interface CycleFocus {
+  readonly currentPackage: string;
+  readonly packageDepth: number;
+}
+
+export interface CycleSelection {
+  readonly highlights: readonly CycleHighlight[];
+  readonly selectedIds: readonly string[];
+  readonly setSelected: (id: string, selected: boolean) => void;
+}

package/src/types/graphInteraction.ts

@@ -0,0 +1,9 @@
+export interface GraphInteractionState {
+  readonly hoveredNodeId: string | null;
+  readonly selectedNodeIds: readonly string[];
+}
+
+export interface GraphInteractionEvent {
+  readonly id: string;
+  readonly type: 'pointer-enter' | 'pointer-leave' | 'select' | 'unselect';
+}

package/src/types/parserSelection.ts

@@ -0,0 +1,11 @@
+import type { DetectedLanguage } from '@ankhorage/project-detector/types';
+
+import type { Language } from '../shared/types';
+
+/** pkgviz's parser choice, not a generic project's single language or a probability. */
+export interface ParserSelection {
+  readonly language: Language;
+  readonly score: number;
+  readonly indicators: readonly string[];
+  readonly candidates: readonly DetectedLanguage[];
+}

package/src/types/projectAnalysis.ts

@@ -0,0 +1,20 @@
+import type { ElementsDefinition } from 'cytoscape';
+
+import type { ParsedDirectory } from '@/shared/types';
+import type { Audit } from '@/types/audit';
+import type { ParserSelection } from '@/types/parserSelection';
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+export interface ProjectSnapshot {
+  readonly files: ParsedDirectory;
+  readonly graph: ElementsDefinition;
+  readonly language: ParserSelection;
+  readonly projectPath: string;
+  readonly timeStart: number;
+}
+
+export interface ProjectOverview {
+  readonly graph: ElementsDefinition;
+  readonly tree: readonly ProjectTreeNode[];
+  readonly evaluation: Audit['evaluation'];
+}

package/src/types/projectAnalysisActionResult.ts

@@ -0,0 +1,2 @@
+export type ProjectAnalysisActionResult<T> =
+  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly error: string };

package/src/types/projectTree.ts

@@ -0,0 +1,7 @@
+export interface ProjectTreeNode {
+  readonly children?: readonly ProjectTreeNode[];
+  readonly graphPackage: string;
+  readonly id: string;
+  readonly kind: 'directory' | 'file';
+  readonly label: string;
+}

package/src/utils/filter/filterByPackagePrefix.ts

@@ -1,16 +1,34 @@
+import { isIntrinsicGraphNode } from '@/utils/filter/isIntrinsicGraphNode';
+
+/***
+ * Filters project descendants while retaining their adjacent external dependency endpoints.
+ * @performance Use endpoint sets to retain adjacent vendors without per-vendor edge scans.
+ */
 export function filterByPackagePrefix(
   allElements: cytoscape.ElementsDefinition,
   packagePrefix: string
 ): cytoscape.ElementsDefinition {
-  // PackageView entrypoint, no prefix
-  if (!packagePrefix) return allElements;
+  const normalizedPrefix = packagePrefix.replace(/\.+$/, '');
+  if (!normalizedPrefix) return allElements;
 
-  // Active filtering (subpackage view)
-  const pkgPrefix = packagePrefix.endsWith('.') ? packagePrefix : packagePrefix + '.';
-  const allowedNodes = allElements.nodes.filter(node => {
-    return (node.data.id as string).startsWith(pkgPrefix);
+  const descendantPrefix = normalizedPrefix + '.';
+  const projectNodes = allElements.nodes.filter(node => {
+    const id = node.data.id ?? '';
+    return isIntrinsicGraphNode(node) && id.startsWith(descendantPrefix);
   });
-
+  const projectIds = new Set(projectNodes.map(node => node.data.id));
+  const connectedIds = new Set(
+    allElements.edges.flatMap(edge =>
+      projectIds.has(edge.data.source) || projectIds.has(edge.data.target)
+        ? [edge.data.source, edge.data.target]
+        : []
+    )
+  );
+  const allowedNodes = allElements.nodes.filter(
+    node =>
+      projectIds.has(node.data.id) ||
+      (!isIntrinsicGraphNode(node) && connectedIds.has(String(node.data.id)))
+  );
   const allowedNodeIds = new Set(allowedNodes.map(node => node.data.id));
   const allowedEdges = allElements.edges.filter(
     edge => allowedNodeIds.has(edge.data.source) && allowedNodeIds.has(edge.data.target)

package/src/utils/filter/filterEmptyPackages.ts

@@ -1,36 +1,35 @@
-import { ElementsDefinition } from 'cytoscape';
+import type { ElementsDefinition } from 'cytoscape';
 
-/**
- * Returns root package if only one inside, or '' (root folder)
- */
-function getRootPackage(elements: ElementsDefinition) {
-  const rootPackages = elements.nodes.filter(n => {
-    return !n.data.id?.includes('.');
-  });
-  return rootPackages.length > 1 ? '' : (rootPackages[0].data.id as string);
-}
+import { isIntrinsicGraphNode } from '@/utils/filter/isIntrinsicGraphNode';
 
-/**
- * Filter empty packages from graph (skip to next interesting package)
+/***
+ * Skips a unique chain of structural project packages, stopping before real dependency endpoints.
+ * @performance Use full-graph indexes: navigation must not depend on depth projection or vendors.
+ * Preserve real isolated leaves and branching packages rather than silently filtering them away.
  */
 export function filterEmptyPackages(currentPackage: string, elements: ElementsDefinition): string {
-  const nodes = elements.nodes.map(n => n.data.id!); // Non-null assertion
-
-  if (!currentPackage) return getRootPackage(elements);
-
-  while (true) {
-    const childPackages = nodes.filter(
-      id =>
-        id.startsWith(currentPackage + '.') &&
-        id.split('.').length === currentPackage.split('.').length + 1
-    );
-
-    if (childPackages.length === 1) {
-      currentPackage = childPackages[0];
-    } else {
-      break;
-    }
+  const children = new Map<string, string[]>();
+  for (const node of elements.nodes.filter(isIntrinsicGraphNode)) {
+    const id = String(node.data.id ?? '');
+    if (!id) continue;
+    const boundary = id.lastIndexOf('.');
+    const parent = boundary < 0 ? '' : id.slice(0, boundary);
+    const siblings = children.get(parent) ?? [];
+    siblings.push(id);
+    children.set(parent, siblings);
   }
+  const connected = new Set(elements.edges.flatMap(edge => [edge.data.source, edge.data.target]));
+  return descend(currentPackage, children, connected);
+}
 
-  return currentPackage;
+/*** Descends only when the next package is a relationship-free structural container. */
+function descend(
+  scope: string,
+  children: ReadonlyMap<string, readonly string[]>,
+  connected: ReadonlySet<string>
+): string {
+  const candidates = children.get(scope) ?? [];
+  const next = candidates[0];
+  if (candidates.length !== 1 || !next || connected.has(next) || !children.has(next)) return scope;
+  return descend(next, children, connected);
 }