pkgviz 0.7.2 → 0.7.4

package/src/app/utils/parser/python/parseFile.ts

@@ -0,0 +1,171 @@
+'use server';
+import type { ParsedFile, MethodCall, MethodDefinition, ImportDefinition } from '@/shared/types';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { extractPythonPackageFromImport } from '@/app/utils/parser/python/extractPythonPackageFromImport';
+
+/**
+ * Extracts module path from Python __init__.py structure.
+ */
+function extractModulePath(filePath: string, projectRoot: string): string {
+  const relativePath = path.relative(projectRoot, filePath);
+  const parts = relativePath.split(path.sep);
+
+  // Remove the filename
+  parts.pop();
+
+  // Join with dots for Python module notation
+  return parts.join('.');
+}
+
+/**
+ * Extracts import statements from Python code.
+ */
+function extractImports(content: string): ImportDefinition[] {
+  const imports: ImportDefinition[] = [];
+
+  // Match: import module
+  // Match: import module as alias
+  // Match: from module import something
+  const importRegex =
+    /(?:^|\n)\s*(?:from\s+([\w.]+)\s+)?import\s+([\w\s,*]+?)(?:\s+as\s+\w+)?(?:\s|$|#)/gm;
+
+  let match;
+  while ((match = importRegex.exec(content)) !== null) {
+    const fromModule = match[1];
+    const importedItems = match[2];
+
+    if (fromModule) {
+      // from X import Y
+      const pkg = extractPythonPackageFromImport(fromModule);
+      const isIntrinsic = fromModule.startsWith('.');
+
+      imports.push({
+        name: fromModule,
+        pkg,
+        isIntrinsic,
+      });
+    } else {
+      // import X, Y, Z
+      const mods = importedItems.split(',').map(m => m.trim());
+      for (const mod of mods) {
+        const pkg = extractPythonPackageFromImport(mod);
+        imports.push({
+          name: mod,
+          pkg,
+          isIntrinsic: false,
+        });
+      }
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Extracts the class name from Python content.
+ */
+function extractClassName(content: string, fileName: string): string {
+  // Try to find class declaration
+  const classMatch = content.match(/^class\s+([A-Za-z0-9_]+)/m);
+  if (classMatch) {
+    return classMatch[1];
+  }
+
+  // Fallback to filename without extension
+  return path.basename(fileName, path.extname(fileName));
+}
+
+/**
+ * Extracts method/function definitions from Python content.
+ */
+function extractMethodDefinitions(content: string): MethodDefinition[] {
+  const methods: MethodDefinition[] = [];
+
+  // Match function definitions: def method_name(params): or async def method_name(params):
+  const methodRegex =
+    /(?:^|\n)\s*(async\s+)?def\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*$$([^)]*)$$\s*(?:->([^:]+))?:/gm;
+
+  let match;
+  while ((match = methodRegex.exec(content)) !== null) {
+    const name = match[2];
+    const paramsStr = match[3];
+    const returnType = match[4]?.trim() || 'None';
+
+    // Parse parameters
+    const params = paramsStr
+      .split(',')
+      .map(p => p.trim())
+      .filter(p => p && p !== 'self' && p !== 'cls');
+
+    // Determine visibility (Python convention: _ prefix = protected, __ prefix = private)
+    let visibility: 'public' | 'protected' | 'private' | 'default' = 'public';
+    if (name.startsWith('__') && !name.endsWith('__')) {
+      visibility = 'private';
+    } else if (name.startsWith('_')) {
+      visibility = 'protected';
+    }
+
+    methods.push({
+      name,
+      returnType,
+      parameters: params,
+      visibility,
+    });
+  }
+
+  return methods;
+}
+
+/**
+ * Extract method calls from Python content.
+ */
+function extractMethodCalls(content: string): MethodCall[] {
+  const calls: MethodCall[] = [];
+
+  // Match: object.method( or self.method(
+  const callRegex = /([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g;
+
+  let match;
+  while ((match = callRegex.exec(content)) !== null) {
+    const callee = match[1];
+    const method = match[2];
+
+    // Skip common built-in methods to reduce noise
+    if (
+      ['append', 'extend', 'pop', 'remove', 'join', 'split', 'strip'].includes(method) &&
+      ['str', 'list', 'dict', 'set'].includes(callee)
+    ) {
+      continue;
+    }
+
+    calls.push({ callee, method });
+  }
+
+  return calls;
+}
+
+/**
+ * Parses a Python file and returns metadata useful for diagram generation.
+ */
+export async function parsePythonFile(fullPath: string, projectRoot: string): Promise<ParsedFile> {
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const fileName = path.basename(fullPath);
+
+  const className = extractClassName(content, fileName);
+  const modulePath = extractModulePath(fullPath, projectRoot);
+  const imports = extractImports(content);
+  const methods = extractMethodDefinitions(content);
+  const calls = extractMethodCalls(content);
+  const relativePath = path.relative(projectRoot, fullPath);
+
+  return {
+    className,
+    package: modulePath,
+    imports,
+    methods,
+    calls,
+    path: relativePath,
+  };
+}

package/src/app/utils/parser/typescript/extractTypeScriptPackageFromImport.ts

@@ -0,0 +1,18 @@
+import { toPosix } from '@/shared/utils/toPosix';
+
+/**
+ * Extracts the package path from an import string.
+ * @example 'lodash/debounce'     => 'lodash'
+ * @example '@nestjs/common'      => '@nestjs/common'
+ * @example './components/Button' => './components'
+ */
+export function extractTypeScriptPackageFromImport(imp: string): string {
+  const segments = toPosix(imp).split('/');
+  const pathSegments = segments.slice(0, -1).join('/'); // Remove file name
+  const replacedAlias = pathSegments.startsWith('@/')
+    ? pathSegments.replace(/^@/, 'src')
+    : pathSegments;
+
+  // Remove file/class-like suffixes (e.g., 'Button.tsx')
+  return replacedAlias.split('/').join('.');
+}

package/src/app/utils/parser/typescript/parseFile.ts

@@ -0,0 +1,130 @@
+import type { ParsedFile, MethodCall, MethodDefinition, ImportDefinition } from '@/shared/types';
+
+import fs from 'node:fs/promises';
+import { basename, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { extractTypeScriptPackageFromImport } from '@/app/utils/parser/typescript/extractTypeScriptPackageFromImport';
+import { toPosix } from '@/shared/utils/toPosix';
+import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+
+/**
+ * Extracts import statements from TypeScript code.
+ */
+function extractImports(content: string, filename: string): ImportDefinition[] {
+  const sourceFile = ts.createSourceFile('temp.ts', content, ts.ScriptTarget.Latest, true);
+  const imports: ImportDefinition[] = [];
+
+  sourceFile.forEachChild(node => {
+    if (!ts.isImportDeclaration(node)) return;
+
+    const fullPath = toPosix(filename).split('/').slice(0, -1).join('/');
+    const moduleSpecifier = (node.moduleSpecifier as ts.StringLiteral).text;
+
+    function resolveImportPath(curDir: string, specifier: string) {
+      const root = parseProjectPath();
+
+      if (specifier.startsWith('./') || specifier.startsWith('../'))
+        return {
+          isIntrinsic: true,
+          resolvedPath: resolve(curDir, specifier).slice(root.length + 1),
+        };
+
+      if (specifier.startsWith('@/'))
+        return {
+          isIntrinsic: true,
+          resolvedPath: specifier.replace(/^@/, 'src'),
+        };
+
+      return { isIntrinsic: false, resolvedPath: specifier };
+    }
+
+    const { resolvedPath, isIntrinsic } = resolveImportPath(fullPath, moduleSpecifier);
+
+    const pkg = extractTypeScriptPackageFromImport(resolvedPath);
+    imports.push({ name: pkg, pkg, isIntrinsic });
+  });
+
+  return imports;
+}
+
+/**
+ * Extracts the class name from the content and filename fallback.
+ */
+function extractClassName(content: string, fileName: string): string {
+  const classMatch = content.match(/class\s+(\w+)/);
+  if (classMatch) {
+    return classMatch[1];
+  }
+  /*** @todo Don't return this fallback, search for functional wrapper instead */
+  return basename(fileName, '.ts');
+}
+
+/**
+ * Extracts method definitions from TypeScript content.
+ */
+function extractMethodDefinitions(content: string): MethodDefinition[] {
+  const sourceFile = ts.createSourceFile('temp.ts', content, ts.ScriptTarget.Latest, true);
+  const methods: MethodDefinition[] = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isMethodDeclaration(node) && node.name) {
+      const name = node.name.getText();
+      const returnType = node.type?.getText() ?? 'void';
+      const parameters = node.parameters.map(p => p.getText());
+      const modifiers = ts.getCombinedModifierFlags(node);
+      let visibility: MethodDefinition['visibility'] = 'default';
+      if (modifiers & ts.ModifierFlags.Private) visibility = 'private';
+      else if (modifiers & ts.ModifierFlags.Protected) visibility = 'protected';
+      else if (modifiers & ts.ModifierFlags.Public) visibility = 'public';
+
+      methods.push({ name, returnType, parameters, visibility });
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+
+  return methods;
+}
+
+/**
+ * Extracts method calls from TypeScript content.
+ */
+function extractMethodCalls(content: string): MethodCall[] {
+  const sourceFile = ts.createSourceFile('temp.ts', content, ts.ScriptTarget.Latest, true);
+  const calls: MethodCall[] = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      const callee = node.expression.expression.getText();
+      const method = node.expression.name.getText();
+      calls.push({ callee, method });
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+
+  return calls;
+}
+
+/**
+ * Parses a TypeScript file and returns metadata useful for diagram generation.
+ */
+export async function parseFile(fullPath: string, projectRoot: string): Promise<ParsedFile> {
+  const posixFullPath = toPosix(fullPath);
+  const content = await fs.readFile(posixFullPath, 'utf-8');
+  const relativePath = toPosix(relative(projectRoot, posixFullPath));
+  const segments = relativePath.split('/');
+  const segmentedPath = segments.slice(0, -1);
+
+  return {
+    className: extractClassName(content, fullPath),
+    imports: extractImports(content, fullPath),
+    methods: extractMethodDefinitions(content),
+    calls: extractMethodCalls(content),
+    package: segmentedPath.join('.'),
+    path: relativePath,
+  };
+}

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,34 @@
+'use client';
+import React from 'react';
+import { ChevronRight, Home } from 'lucide-react';
+import Link from 'next/link';
+
+export default function Breadcrumb({ path, onNavigate }: BreadcrumbProps) {
+  const parts = path.split('/') || [''];
+
+  return (
+    <nav className="flex items-center space-x-1 text-sm">
+      <Link href="#" onClick={() => onNavigate('')} className="flex items-center text-foreground">
+        <Home className="h-4 w-4 mr-1" />
+      </Link>
+
+      {parts.map((part, index) => {
+        const currentPath = parts.length ? parts.slice(0, index + 1).join('.') : '';
+
+        return (
+          <div key={index} className="flex items-center">
+            <ChevronRight className="h-4 w-4 text-foreground opacity-20" />
+            <Link href="#" onClick={() => onNavigate(currentPath)} className="ml-1 text-foreground">
+              {part}
+            </Link>
+          </div>
+        );
+      })}
+    </nav>
+  );
+}
+
+interface BreadcrumbProps {
+  readonly path: string;
+  readonly onNavigate: (path: string) => void;
+}

package/src/components/Cytoscape.tsx

@@ -0,0 +1,23 @@
+'use client';
+import type { ElementsDefinition } from 'cytoscape';
+
+import React from 'react';
+import { useCytoscape } from '@/components/useCytoscape';
+import ZoomInput from '@/components/ZoomInput';
+
+export function Cytoscape({ currentPackage, packageGraph, setCurrentPackage }: CytoscapeProps) {
+  const { cyRef, cyInstance } = useCytoscape(packageGraph, currentPackage, setCurrentPackage);
+
+  return (
+    <div className="flex flex-col w-full px-8 flex-1 gap-2">
+      <div ref={cyRef} className="h-[calc(100%-65px)]" />
+      <ZoomInput cyInstance={cyInstance} />
+    </div>
+  );
+}
+
+interface CytoscapeProps {
+  readonly currentPackage: string;
+  readonly packageGraph: ElementsDefinition | null;
+  readonly setCurrentPackage: (path: string) => void;
+}

package/src/components/Header.tsx

@@ -0,0 +1,28 @@
+import React, { type PropsWithChildren } from 'react';
+
+import ThemeToggle from '@/components/ThemeToggle';
+import { t } from '@/i18n/i18n';
+import { getProjectName } from '@/shared/utils/getProjectName';
+
+export default function Header({ children, title }: HeaderProps) {
+  const projectName = getProjectName();
+
+  return (
+    <header className="flex flex-row items-center justify-between text-blue-50 bg-blue-500 dark:bg-blue-950 border-b-1 border-b-neutral-200 mb-1 dark:border-b-blue-800 p-2 pb-1 gap-4">
+      {/* Left */}
+      <div className="flex flex-row items-center justify-start">
+        <h1 className="ml-4">{projectName}</h1>
+        <span className="ml-2 opacity-20">&#47;</span>
+        {title && <strong className="mx-2">{t(title)}</strong>}
+        {children}
+      </div>
+
+      {/* Right */}
+      <ThemeToggle />
+    </header>
+  );
+}
+
+interface HeaderProps extends PropsWithChildren {
+  readonly title?: string;
+}

package/src/components/Loader.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { LucideLoader } from 'lucide-react';
+
+export default function Loader() {
+  return (
+    <div data-testid="loader" className="h-full flex items-center justify-center">
+      <LucideLoader />
+    </div>
+  );
+}

package/src/components/Setting.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+const Setting: React.FC<SettingProps> = ({ children }) => {
+  return (
+    <div className="ml-[.8rem] px-[.8rem] py-2  bg-white dark:bg-neutral-900 border-b border-b-neutral-200 dark:border-b-neutral-800">
+      {children}
+    </div>
+  );
+};
+
+Setting.displayName = 'Setting';
+
+export default Setting;
+
+interface SettingProps {
+  readonly children: React.ReactNode;
+}

package/src/components/Settings.tsx

@@ -0,0 +1,189 @@
+'use client';
+import dynamic from 'next/dynamic';
+import { ChevronDownIcon, DownloadIcon } from 'lucide-react';
+import { Select, Slider } from 'radix-ui';
+import type React from 'react';
+import Setting from '@/components/Setting';
+import Switch from '@/components/Switch';
+import { useSettings } from '@/contexts/SettingsContext';
+import { t } from '@/i18n/i18n';
+import { downloadAuditJsonAction, downloadAuditXmlAction } from '@/app/actions/audit.actions';
+
+const Settings: React.FC = () => {
+  const {
+    cytoscapeLayout,
+    cytoscapeLayoutSpacing,
+    maxSubPackageDepth,
+    showCompoundNodes,
+    showVendorPackages,
+    subPackageDepth,
+    setCytoscapeLayout,
+    setCytoscapeLayoutSpacing,
+    setSubPackageDepth,
+    toggleShowCompoundNodes,
+    toggleShowVendorPackages,
+  } = useSettings();
+
+  const handleDownloadJson = async () => {
+    const { data, filename } = await downloadAuditJsonAction();
+    const blob = new Blob([data], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  const handleDownloadXml = async () => {
+    const { data, filename } = await downloadAuditXmlAction();
+    const blob = new Blob([data], { type: 'application/xml' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <div className="md:pt-14 border-r bg-neutral-100 border-r-neutral-200 dark:border-r-neutral-800 dark:bg-neutral-950">
+      {/* Audit Download */}
+      <h3>{t('settings.download')}</h3>
+      <div>
+        {/* JSON Audit Download */}
+        <Setting>
+          <button
+            onClick={handleDownloadJson}
+            className="flex flex-row items-center content-start text-xs cursor-pointer hover:text-blue-600 dark:hover:text-blue-400"
+          >
+            <DownloadIcon size={8} className="mr-1" />
+            <span>JSON</span>
+          </button>
+        </Setting>
+        {/* XML Audit Download */}
+        <Setting>
+          <button
+            onClick={handleDownloadXml}
+            className="flex flex-row items-center content-start text-xs cursor-pointer hover:text-blue-600 dark:hover:text-blue-400"
+          >
+            <DownloadIcon size={8} className="mr-1" />
+            <span>XML</span>
+          </button>
+        </Setting>
+      </div>
+
+      <h3>{t('settings.filter')}</h3>
+      {/* Whether to show vendor packages */}
+      <Setting>
+        <Switch
+          id="switch-show-vendor-packages"
+          label={t('settings.showVendorPackages')}
+          onToggle={() => {
+            toggleShowVendorPackages();
+          }}
+          value={showVendorPackages}
+        />
+      </Setting>
+
+      {/* Whether to show compound nodes */}
+      <Setting>
+        <Switch
+          id="switch-show-compound-nodes"
+          label={t('settings.showCompoundNodes')}
+          onToggle={() => {
+            toggleShowCompoundNodes();
+          }}
+          value={showCompoundNodes}
+        />
+      </Setting>
+
+      {/* How many sub package levels to show */}
+      <>
+        <h3>{`${t('settings.subPackageDepth')}: ${subPackageDepth}`}</h3>
+        <Setting>
+          <Slider.Root
+            id="subPackageDepth"
+            min={1}
+            max={maxSubPackageDepth}
+            step={1}
+            value={[subPackageDepth]}
+            onValueChange={([v]) => setSubPackageDepth(Number(v.toFixed(1)))}
+            aria-label="Subpackage depth"
+            className="relative flex h-5 w-56 touch-none select-none items-center"
+          >
+            <Slider.Track className="relative h-1.5 grow rounded-full bg-neutral-200 dark:bg-neutral-800">
+              <Slider.Range className="absolute h-1.5 rounded-full bg-blue-600 dark:bg-blue-400" />
+            </Slider.Track>
+            <Slider.Thumb className="block h-4 w-4 rounded-full border border-neutral-300 bg-white shadow focus:outline-none focus:ring-2 focus:ring-blue-500 dark:border-neutral-600 dark:bg-neutral-100" />
+          </Slider.Root>
+        </Setting>
+      </>
+
+      <h3>{t('settings.layout')}</h3>
+      <Setting>
+        <Select.Root value={cytoscapeLayout} onValueChange={setCytoscapeLayout}>
+          <Select.Trigger
+            aria-label={t('cytoscapeLayout')}
+            className="inline-flex items-center justify-between w-44 h-9 rounded-md px-3 border"
+          >
+            <Select.Value className="text-foreground" />
+            <Select.Icon>
+              <ChevronDownIcon />
+            </Select.Icon>
+          </Select.Trigger>
+          <Select.Portal>
+            <Select.Content
+              position="popper"
+              side="bottom"
+              align="start"
+              sideOffset={6}
+              className="z-50 min-w-(--radix-select-trigger-width) rounded-md border bg-white dark:bg-neutral-900 shadow-md"
+            >
+              <Select.Viewport className="p-1">
+                <Select.Group>
+                  {['breadthfirst', 'circle', 'concentric', 'elk', 'grid'].map(layout => (
+                    <Select.Item
+                      key={layout}
+                      value={layout}
+                      textValue={t(layout)}
+                      className="px-2 py-1.5 rounded hover:bg-neutral-100 dark:hover:bg-neutral-800"
+                    >
+                      <Select.ItemText>{t(layout)}</Select.ItemText>
+                    </Select.Item>
+                  ))}
+                </Select.Group>
+              </Select.Viewport>
+            </Select.Content>
+          </Select.Portal>
+        </Select.Root>
+      </Setting>
+
+      <h3>
+        {t('settings.layoutSpacing')}: {cytoscapeLayoutSpacing}
+      </h3>
+      {/* Which Cytoscape layout spacing */}
+      <Setting>
+        <Slider.Root
+          id="spacing"
+          min={0.1}
+          max={1}
+          step={0.1}
+          value={[cytoscapeLayoutSpacing]}
+          onValueChange={([v]) => setCytoscapeLayoutSpacing(Number(v.toFixed(1)))}
+          aria-label="Layout spacing"
+          className="relative flex h-5 w-56 touch-none select-none items-center"
+        >
+          <Slider.Track className="relative h-1.5 grow rounded-full bg-neutral-200 dark:bg-neutral-800">
+            <Slider.Range className="absolute h-1.5 rounded-full bg-blue-600 dark:bg-blue-400" />
+          </Slider.Track>
+          <Slider.Thumb className="block h-4 w-4 rounded-full border border-neutral-300 bg-white shadow focus:outline-none focus:ring-2 focus:ring-blue-500 dark:border-neutral-600 dark:bg-neutral-100" />
+        </Slider.Root>
+      </Setting>
+    </div>
+  );
+};
+
+export default dynamic(() => Promise.resolve(Settings), {
+  ssr: false,
+});

package/src/components/Switch.tsx

@@ -0,0 +1,31 @@
+'use client';
+import React from 'react';
+import { Switch } from 'radix-ui';
+
+export default function RadixSwitch({ id, label, value, onToggle }: ISwitch) {
+  return (
+    <form>
+      <div className="flex items-center justify-between h-[20px]">
+        <label className="pr-[15px] leading-none text-foreground whitespace-nowrap" htmlFor={id}>
+          {label}
+        </label>
+        <Switch.Root
+          className="relative h-[18px] w-[42px] cursor-default rounded-full bg-neutral-200 dark:bg-neutral-800 outline-none data-[state=checked]:bg-neutral-200 dark:data-[state=checked]:bg-gray-700"
+          defaultChecked={value}
+          id={id}
+          checked={value}
+          onCheckedChange={onToggle}
+        >
+          <Switch.Thumb className="block size-[16px] translate-x-0.5 rounded-full bg-neutral-500 dark:bg-neutral-500 transition-transform duration-100 will-change-transform data-[state=checked]:bg-blue-500 dark:data-[state=checked]:bg-white data-[state=checked]:translate-x-[24px]" />
+        </Switch.Root>
+      </div>
+    </form>
+  );
+}
+
+interface ISwitch {
+  readonly id: string;
+  readonly label: string;
+  readonly value: boolean;
+  readonly onToggle: () => void;
+}

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,25 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { useTheme } from 'next-themes';
+
+export default function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return null;
+
+  const active = theme === 'system' ? resolvedTheme : theme;
+  const isDark = active === 'dark';
+
+  return (
+    <button
+      onClick={() => setTheme(isDark ? 'light' : 'dark')}
+      aria-label="Toggle dark mode"
+      className="rounded-lg px-3 py-2 border border-blue-400 dark:border-blue-600 text-xs cursor-pointer"
+      title={`Switch to ${isDark ? 'light' : 'dark'} mode`}
+    >
+      {isDark ? '🌙 Dark' : '☀️ Light'}
+    </button>
+  );
+}