pkgviz 0.7.7 → 0.8.0

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);
 }

package/src/utils/filter/filterSubPackagesFromDepth.ts

@@ -1,6 +1,6 @@
 import type { EdgeDefinition, ElementsDefinition } from 'cytoscape';
 
-/**
+/***
  * Compute the minimal set of "root" packages that have no ancestor in the list.
  * Example: ['x.y', 'x.y.z', 'a', 'a.c.x'] => ['a', 'x.y']
  */
@@ -16,7 +16,7 @@ function findRoots(packages: string[]): string[] {
   return roots;
 }
 
-/**
+/***
  * Ascend from a package to its nearest ancestor that is in the `roots` set.
  */
 function nearestRoot(pkg: string, roots: Set<string>): string {
@@ -31,7 +31,7 @@ function nearestRoot(pkg: string, roots: Set<string>): string {
   return pkg;
 }
 
-/**
+/***
  * Given a root and a leaf pkg, return the visible ancestor at `maxDepth`
  * under the root, preferring the deepest existing package <= target depth.
  *
@@ -59,7 +59,7 @@ function visibleAncestorForDepth(
   return root; // fallback
 }
 
-/**
+/***
  * Global maximum depth across all roots.
  * Depth is counted relative to the nearest root: root=1, root.child=2, etc.
  */
@@ -79,7 +79,7 @@ export function getMaxDepth(elements: ElementsDefinition): number {
   return maxDepth;
 }
 
-/**
+/***
  * Maximum depth per root, e.g. { 'a': 3, 'x.y': 2 }.
  */
 export function getMaxDepthByRoot(elements: ElementsDefinition): Record<string, number> {
@@ -96,19 +96,17 @@ export function getMaxDepthByRoot(elements: ElementsDefinition): Record<string,
   return result;
 }
 
-/**
+/***
  * Filters sub-packages so only the desired number of levels under each root are shown.
- *
- * @param elements - Cytoscape elements
- * @param allowSelfLoops - Keep self loops after lifting/aggregation
- * @param maxDepth - Number of levels to keep under each root (1 = roots only, 2 = +children, etc.)
+ * @performance Aggregate weights and origin IDs in local maps without repeatedly copying growing
+ * evidence arrays. Inputs remain immutable; a large lifted bundle must stay linear in edge count.
  */
 export function filterSubPackagesByDepth(
   elements: ElementsDefinition,
-  allowSelfLoops: boolean = false,
-  maxDepth: number = 1
+  allowSelfLoops = false,
+  maxDepth = 1
 ): ElementsDefinition {
-  const allPackages = elements.nodes.map(n => n.data.id as string);
+  const allPackages = elements.nodes.map(n => n.data.id!);
   const existingSet = new Set(allPackages);
 
   // 1) Identify minimal roots (no ancestor present)
@@ -125,14 +123,15 @@ export function filterSubPackagesByDepth(
 
   // 3) Visible nodes = unique set of chosen ancestors
   const visibleNodeIds = new Set<string>(pkgToVisible.values());
-  const filteredNodes = elements.nodes.filter(n => visibleNodeIds.has(n.data.id as string));
+  const filteredNodes = elements.nodes.filter(n => visibleNodeIds.has(n.data.id!));
 
   // 4) Lift & aggregate edges to visible ancestors (sum weights)
   const edgeMap = new Map<string, EdgeDefinition>();
+  const edgeOrigins = new Map<string, string[]>();
 
   for (const e of elements.edges) {
-    const rawSource = e.data.source as string;
-    const rawTarget = e.data.target as string;
+    const rawSource = e.data.source;
+    const rawTarget = e.data.target;
 
     const liftedSource = pkgToVisible.get(rawSource) ?? rawSource;
     const liftedTarget = pkgToVisible.get(rawTarget) ?? rawTarget;
@@ -145,13 +144,17 @@ export function filterSubPackagesByDepth(
     }
 
     const key = `${liftedSource}->${liftedTarget}`;
+    const origins = edgeOrigins.get(key) ?? [];
+    origins.push(e.data.id ?? `${rawSource}->${rawTarget}`);
+    edgeOrigins.set(key, origins);
     if (!edgeMap.has(key)) {
       // clone with lifted endpoints; keep your metadata; (optionally set a stable id)
       edgeMap.set(key, {
         ...e,
         data: {
           ...e.data,
-          // id: key, // uncomment if you want stable, deduped edge ids
+          id: key,
+          originalEdgeIds: origins,
           source: liftedSource,
           target: liftedTarget,
           // initialize aggregated weight

package/src/utils/filter/filterVendorPackages.ts

@@ -1,6 +1,6 @@
 import type { ElementsDefinition } from 'cytoscape';
 
-/**
+/***
  * Filters vendor packages by known package prefix
  */
 export function filterVendorPackages(elements: ElementsDefinition): ElementsDefinition {

package/src/utils/filter/isIntrinsicGraphNode.ts

@@ -0,0 +1,8 @@
+import type { NodeDefinition } from 'cytoscape';
+
+/*** Identifies project nodes using the graph builder's classification, not namespace spelling. */
+export function isIntrinsicGraphNode(node: NodeDefinition): boolean {
+  if (typeof node.data.isIntrinsic === 'boolean') return node.data.isIntrinsic;
+  const classes = Array.isArray(node.classes) ? node.classes : (node.classes ?? '').split(/\s+/);
+  return !classes.includes('isVendor');
+}