pkgviz 0.7.1 → 0.7.3

package/src/shared/utils/getProjectName.ts

@@ -0,0 +1,3 @@
+import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+
+export const getProjectName = () => parseProjectPath().split('/').pop() || '{unknown}';

package/src/shared/utils/parseEnv.ts

@@ -0,0 +1,91 @@
+/**
+ * Parses an environment variable value into the appropriate type.
+ * @example 'true'  => true
+ * @example 'false' => false
+ * @example '123'   => 123
+ * @example 'text'  => 'text'
+ */
+export const parseEnv = (name: string, value: string | undefined) => {
+  if (!value) return undefined;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (!isNaN(Number(value))) return Number(value);
+  return value;
+};
+
+/**
+ * Determines the active Cytoscape layout
+ * @default 'concentric'
+ * @todo Create enum for the layouts
+ * @returns 'grid' | 'circle' | 'elk' | 'concentric'
+ */
+export const getCytoscapeLayout = () => {
+  const env = parseEnv('NEXT_PUBLIC_SETTINGS_LAYOUT', process.env.NEXT_PUBLIC_SETTINGS_LAYOUT);
+  return env === 'grid'
+    ? 'grid'
+    : env === 'circle'
+      ? 'circle'
+      : env === 'elk'
+        ? 'elk'
+        : 'concentric';
+};
+
+/**
+ * Determines the active Cytoscape layout spacing.
+ * @returns number
+ * @default 1
+ * @min 0.1
+ * @max 1
+ */
+export const getCytoscapeLayoutSpacing = () => {
+  const env = parseEnv(
+    'NEXT_PUBLIC_SETTINGS_LAYOUT_SPACING',
+    process.env.NEXT_PUBLIC_SETTINGS_LAYOUT_SPACING
+  );
+
+  return isNaN(Number(env)) ? 1 : Number(env);
+};
+
+/**
+ * Determines whether to show compound nodes.
+ * @default true
+ * @returns boolean
+ */
+export const getShowCompoundNodes = () => {
+  const env = parseEnv(
+    'NEXT_PUBLIC_SETTINGS_SHOW_COMPOUNDNODES',
+    process.env.NEXT_PUBLIC_SETTINGS_SHOW_COMPOUNDNODES
+  );
+
+  return env === false ? false : true;
+};
+
+/**
+ * Determines whether to show vendor packages.
+ * @default false
+ * @returns boolean
+ */
+export const getShowVendorPackages = () => {
+  const env = parseEnv(
+    'NEXT_PUBLIC_SETTINGS_SHOW_VENDORPACKAGES',
+    process.env.NEXT_PUBLIC_SETTINGS_SHOW_VENDORPACKAGES
+  );
+
+  return env === true ? true : false;
+};
+
+/**
+ * Determines how many subpackage levels to show.
+ * @default 1
+ * @min 1
+ * @max {automatic based on package depth}
+ * @returns number
+ */
+export const getSubPackageDepth = () => {
+  const env = parseEnv(
+    'NEXT_PUBLIC_SETTINGS_SUBPACKAGE_DEPTH',
+    process.env.NEXT_PUBLIC_SETTINGS_SUBPACKAGE_DEPTH
+  );
+
+  return typeof env === 'string' && env.length ? parseInt(env) : 1;
+};

package/src/shared/utils/parseProjectPath.ts

@@ -0,0 +1,8 @@
+import { toPosix } from '@/shared/utils/toPosix';
+
+export const parseProjectPath = () => {
+  const projectPath = process.env.NEXT_PUBLIC_PROJECT_PATH;
+  if (!projectPath) throw new Error('Missing ENV: NEXT_PUBLIC_PROJECT_PATH');
+
+  return toPosix(projectPath);
+};

package/src/store/useLocalStorage.ts

@@ -0,0 +1,29 @@
+import { useState } from 'react';
+
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue;
+
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? (JSON.parse(item) as T) : initialValue;
+    } catch (error) {
+      console.warn(`Error reading localStorage key "${key}":`, error);
+      return initialValue;
+    }
+  });
+
+  const setValue = (value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      if (typeof window !== 'undefined') {
+        window.localStorage.setItem(key, JSON.stringify(valueToStore));
+      }
+    } catch (error) {
+      console.warn(`Error setting localStorage key "${key}":`, error);
+    }
+  };
+
+  return [storedValue, setValue] as const;
+}

package/src/utils/filter/filterByPackagePrefix.ts

@@ -0,0 +1,23 @@
+export function filterByPackagePrefix(
+  allElements: cytoscape.ElementsDefinition,
+  packagePrefix: string
+): cytoscape.ElementsDefinition {
+  // PackageView entrypoint, no prefix
+  if (!packagePrefix) 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 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)
+  );
+
+  return {
+    nodes: allowedNodes,
+    edges: allowedEdges,
+  };
+}

package/src/utils/filter/filterEmptyPackages.ts

@@ -0,0 +1,36 @@
+import { 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);
+}
+
+/**
+ * Filter empty packages from graph (skip to next interesting package)
+ */
+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;
+    }
+  }
+
+  return currentPackage;
+}

package/src/utils/filter/filterSubPackagesFromDepth.ts

@@ -0,0 +1,170 @@
+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']
+ */
+function findRoots(packages: string[]): string[] {
+  const sorted = [...packages].sort(); // parents before children (lexicographically close enough for dotted paths)
+  const roots: string[] = [];
+
+  for (const pkg of sorted) {
+    if (!roots.some(parent => pkg.startsWith(parent + '.'))) {
+      roots.push(pkg);
+    }
+  }
+  return roots;
+}
+
+/**
+ * Ascend from a package to its nearest ancestor that is in the `roots` set.
+ */
+function nearestRoot(pkg: string, roots: Set<string>): string {
+  if (roots.has(pkg)) return pkg;
+  const parts = pkg.split('.');
+  while (parts.length > 1) {
+    parts.pop();
+    const ancestor = parts.join('.');
+    if (roots.has(ancestor)) return ancestor;
+  }
+  // Fallback: if nothing matched (shouldn't happen if roots are computed from the same list)
+  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.
+ *
+ * Example:
+ *   root = 'a', pkg = 'a.b.c.d', maxDepth=2 → tries 'a.b' (if exists), else falls back to 'a'
+ */
+function visibleAncestorForDepth(
+  root: string,
+  pkg: string,
+  maxDepth: number,
+  existing: Set<string>
+): string {
+  // Depth is counted as: root = depth 1; root.child = depth 2; etc.
+  if (maxDepth <= 1) return root;
+
+  const rootDepth = root.split('.').length;
+  const pkgParts = pkg.split('.');
+  const desiredDepth = Math.min(rootDepth + (maxDepth - 1), pkgParts.length);
+
+  // Walk downwards from desiredDepth to rootDepth until we find an existing node
+  for (let d = desiredDepth; d >= rootDepth; d--) {
+    const candidate = pkgParts.slice(0, d).join('.');
+    if (existing.has(candidate)) return candidate;
+  }
+  return root; // fallback
+}
+
+/**
+ * Global maximum depth across all roots.
+ * Depth is counted relative to the nearest root: root=1, root.child=2, etc.
+ */
+export function getMaxDepth(elements: ElementsDefinition): number {
+  const pkgs = elements.nodes.map(n => String(n.data.id));
+  if (pkgs.length === 0) return 0;
+
+  const roots = findRoots(pkgs);
+  const rootSet = new Set(roots);
+
+  let maxDepth = 1;
+  for (const pkg of pkgs) {
+    const root = nearestRoot(pkg, rootSet);
+    const depth = pkg.split('.').length - root.split('.').length + 1; // root=1
+    if (depth > maxDepth) maxDepth = depth;
+  }
+  return maxDepth;
+}
+
+/**
+ * Maximum depth per root, e.g. { 'a': 3, 'x.y': 2 }.
+ */
+export function getMaxDepthByRoot(elements: ElementsDefinition): Record<string, number> {
+  const pkgs = elements.nodes.map(n => String(n.data.id));
+  const roots = findRoots(pkgs);
+  const rootSet = new Set(roots);
+
+  const result: Record<string, number> = Object.fromEntries(roots.map(r => [r, 1]));
+  for (const pkg of pkgs) {
+    const root = nearestRoot(pkg, rootSet);
+    const depth = pkg.split('.').length - root.split('.').length + 1;
+    if (depth > result[root]) result[root] = depth;
+  }
+  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.)
+ */
+export function filterSubPackagesByDepth(
+  elements: ElementsDefinition,
+  allowSelfLoops: boolean = false,
+  maxDepth: number = 1
+): ElementsDefinition {
+  const allPackages = elements.nodes.map(n => n.data.id as string);
+  const existingSet = new Set(allPackages);
+
+  // 1) Identify minimal roots (no ancestor present)
+  const roots = findRoots(allPackages);
+  const rootSet = new Set(roots);
+
+  // 2) Map every package to its visible ancestor according to maxDepth
+  const pkgToVisible = new Map<string, string>();
+  for (const pkg of allPackages) {
+    const root = nearestRoot(pkg, rootSet);
+    const visible = visibleAncestorForDepth(root, pkg, maxDepth, existingSet);
+    pkgToVisible.set(pkg, visible);
+  }
+
+  // 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));
+
+  // 4) Lift & aggregate edges to visible ancestors (sum weights)
+  const edgeMap = new Map<string, EdgeDefinition>();
+
+  for (const e of elements.edges) {
+    const rawSource = e.data.source as string;
+    const rawTarget = e.data.target as string;
+
+    const liftedSource = pkgToVisible.get(rawSource) ?? rawSource;
+    const liftedTarget = pkgToVisible.get(rawTarget) ?? rawTarget;
+
+    if (!visibleNodeIds.has(liftedSource) || !visibleNodeIds.has(liftedTarget)) {
+      continue;
+    }
+    if (!allowSelfLoops && liftedSource === liftedTarget) {
+      continue;
+    }
+
+    const key = `${liftedSource}->${liftedTarget}`;
+    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
+          source: liftedSource,
+          target: liftedTarget,
+          // initialize aggregated weight
+          weight: (e.data.weight as number | undefined) ?? 1,
+        },
+      });
+    } else {
+      const existing = edgeMap.get(key)!;
+      const add = (e.data.weight as number | undefined) ?? 1;
+      existing.data.weight = ((existing.data.weight as number | undefined) ?? 0) + add;
+    }
+  }
+
+  const filteredEdges = Array.from(edgeMap.values());
+  return { nodes: filteredNodes, edges: filteredEdges };
+}

package/src/utils/filter/filterVendorPackages.ts

@@ -0,0 +1,17 @@
+import type { ElementsDefinition } from 'cytoscape';
+
+/**
+ * Filters vendor packages by known package prefix
+ */
+export function filterVendorPackages(elements: ElementsDefinition): ElementsDefinition {
+  const filteredNodes = elements.nodes.filter(node => !!node.data.isIntrinsic);
+  const allowedNodeIds = new Set(filteredNodes.map(node => node.data.id));
+  const filteredEdges = elements.edges.filter(
+    edge => allowedNodeIds.has(edge.data.source) && allowedNodeIds.has(edge.data.target)
+  );
+
+  return {
+    nodes: filteredNodes,
+    edges: filteredEdges,
+  };
+}

package/src/utils/filter/toggleCompoundNodes.ts

@@ -0,0 +1,40 @@
+import { ElementsDefinition } from 'cytoscape';
+
+/**
+ * Toggles display of compound nodes ('parent' attribute) in the node
+ * @param elements - Cytoscape elements (nodes and edges)
+ * @param show - Whether to show compound nodes
+ * @param currentPackage - Current package path to adjust node names when showing compound nodes
+ * @returns Updated Cytoscape elements with compound nodes toggled
+ */
+export function toggleCompoundNodes(
+  { nodes, edges }: ElementsDefinition,
+  show: boolean,
+  currentPackage: string
+): ElementsDefinition {
+  const updatedNodes = nodes.map(node => {
+    if (!node.data.idInactive) node.data.idInactive = node.data.id;
+    // ACTIVE Compound Nodes
+    if (show && node.data.parentInactive) {
+      node.data.parent = node.data.parentInactive;
+      node.data.parentInactive = undefined;
+    } else if (!show && node.data.parent) {
+      node.data.parentInactive = node.data.parent;
+      node.data.parent = undefined;
+    }
+    return node;
+  });
+
+  const labelledNodes = updatedNodes.map(node => {
+    if (show) {
+      node.data.name = node.data.idInactive.split('.').pop();
+    } else {
+      node.data.name = node.data.idInactive.slice(
+        currentPackage.length ? currentPackage.length + 1 : 0
+      );
+    }
+    return node;
+  });
+
+  return { nodes: labelledNodes, edges };
+}

package/src/utils/hasChildren.ts

@@ -0,0 +1,7 @@
+import type { NodeDataDefinition, NodeDefinition } from 'cytoscape';
+
+/**
+ * Checks if a node (package) has children based on id prefix.
+ */
+export const hasChildren = (node: NodeDefinition, nodes: NodeDataDefinition[]) =>
+  nodes.some(n => n.data.id?.startsWith(`${node.data.id}.`));