pkgviz 0.7.7 → 0.8.0

package/package.json

@@ -4,62 +4,83 @@
     "pkgviz": "bin/pkgviz.ts"
   },
   "files": [
-    "/bin",
-    "/src",
+    "bin",
+    "src",
     "tsconfig.json",
-    ".next"
+    ".next/BUILD_ID",
+    ".next/*.js",
+    ".next/*.json",
+    ".next/server",
+    ".next/static"
   ],
   "type": "module",
   "engines": {
-    "node": ">=22.14.0",
+    "node": ">=24",
     "bun": ">=1.2.18",
     "npm": ">=10.9.2"
   },
-  "version": "0.7.7",
+  "version": "0.8.0",
+  "description": "Analyze and visualize codebases, dependencies, architecture rules, and audit evidence.",
+  "keywords": [
+    "code-analysis",
+    "dependency-graph",
+    "architecture",
+    "visualization",
+    "static-analysis",
+    "cytoscape",
+    "developer-tools",
+    "typescript",
+    "audit",
+    "codebase"
+  ],
   "scripts": {
-    "dev": "next dev --turbopack",
-    "build": "next build",
-    "docs:deploy": "bun --filter forensics-docs run deploy",
+    "dev": "bun run zora:materialize && next dev",
+    "build": "bun run zora:materialize && next build",
     "start": "next start",
-    "lint": "next lint",
-    "format:check": "prettier --check .",
-    "format:write": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml,mjs,cjs,html,css,scss,mdx}\"",
-    "test": "npx @artiphishle/testosterone@0.3.8",
+    "lint": "bun run zora:materialize && ankhorage-eslint . --max-warnings=0",
+    "format:check": "ankhorage-prettier --check .",
+    "format:write": "ankhorage-prettier --write \"**/*.{js,jsx,ts,tsx,json,md,yml,yaml,mjs,cjs,html,css,scss,mdx}\"",
+    "test": "testosterone && bun run test:maven",
     "test:cov": "c8 --reporter=text --reporter=text-summary tsx --test",
-    "test:cov:html": "c8 --report-dir=./test/coverage --reporter=html tsx --test"
+    "test:cov:html": "c8 --report-dir=./test/coverage --reporter=html tsx --test",
+    "lint:fix": "bun run zora:materialize && ankhorage-eslint . --fix --max-warnings=0",
+    "format": "ankhorage-prettier --write .",
+    "knip:check": "bun run zora:materialize && ankhorage-knip",
+    "changeset": "ankhorage-changeset",
+    "changeset:status": "ankhorage-changeset status --since=origin/main",
+    "version-packages": "ankhorage-changeset version",
+    "test:maven": "mvn -B -f maven-plugin/pom.xml test",
+    "zora:materialize": "ANKH_CACHE_DIR=.generated/ankh bunx @ankhorage/ankh@0.10.4 zora create tree-view --web --out .generated/zora/tree-view && ANKH_CACHE_DIR=.generated/ankh bunx @ankhorage/ankh@0.10.4 zora create graph-view --web --out .generated/zora/graph-view"
   },
   "dependencies": {
-    "@artiphishle/testosterone": "^0.3.8",
-    "cytoscape": "^3.33.1",
-    "cytoscape-elk": "^2.3.0",
-    "fp-ts": "^2.16.11",
+    "@ankhorage/dependency-graph": "^0.6.0",
+    "@ankhorage/graph": "^0.2.0",
+    "@ankhorage/graph-cytoscape": "^0.1.1",
+    "@ankhorage/project-detector": "^0.1.0",
+    "@ankhorage/utility": "^1.4.0",
+    "@artiphishle/testosterone": "^0.3.9",
+    "ankh-hooks": "^1.5.2",
+    "cytoscape": "^3.34.3",
     "lucide-react": "^0.487.0",
-    "meta": "^2.2.25",
-    "next": "15.4.10",
+    "next": "16.3.5",
     "next-themes": "^0.4.6",
     "radix-ui": "^1.4.3",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "typescript": "^5.9.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "~6.0.3",
     "xml-js": "^1.6.11"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.3.1",
-    "@tailwindcss/postcss": "^4.1.17",
-    "@types/bun": "^1.3.2",
-    "@types/cytoscape": "^3.31.0",
-    "@types/node": "^20.19.25",
-    "@types/react": "^19.2.5",
+    "@ankhorage/devtools": "^1.16.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^24.13.5",
+    "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
-    "autoprefixer": "^10.4.22",
     "c8": "^10.1.3",
-    "eslint": "^9.39.1",
-    "eslint-config-next": "15.3.0",
     "postcss": "^8.5.6",
-    "prettier": "^3.6.2",
-    "tailwindcss": "^4.1.17",
-    "tailwindcss-cli": "^0.1.2",
-    "tsx": "^4.20.6"
+    "tailwindcss": "^4.1.18",
+    "tsx": "^4.21.0"
   },
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+  "packageManager": "bun@1.4.2"
 }

package/src/app/actions/audit.actions.ts

@@ -1,44 +1,16 @@
 'use server';
-import type { LanguageDetectionResult, ParsedDirectory } from '@/shared/types';
+import { js2xml } from 'xml-js';
 
-import { getParsedFileStructure } from '@/app/utils/getParsedFileStructure';
-import { detectLanguage } from '@/shared/utils/detectLanguage';
-import {
-  getPackageCyclesWithMembers,
-  type PackageCycleDetail,
-} from '@/app/utils/markCyclicPackages';
-import { buildGraph } from '@/app/utils/buildGraph';
+import { createAuditAsync } from '@/features/audit/composition/createAuditAsync';
 import { parseProjectPath } from '@/shared/utils/parseProjectPath';
-import { getProjectName } from '@/shared/utils/getProjectName';
-import { js2xml } from 'xml-js';
+import type { Audit } from '@/types/audit';
 
+/*** Builds the audit payload for the configured project. */
 export async function getAuditAction(): Promise<Audit> {
-  const projectPath = parseProjectPath();
-  const projectName = getProjectName();
-  const timeStart = Date.now();
-  const language = await detectLanguage(projectPath);
-  const files = await getParsedFileStructure();
-  const graph = buildGraph(files);
-  const cyclicPackages = getPackageCyclesWithMembers(files, graph).cycles;
-
-  const audit: Partial<Audit> = {
-    evaluation: {
-      cyclicPackages,
-    },
-    files,
-    meta: {
-      language,
-      projectName,
-      timeStart,
-      timeEnd: timeStart,
-    },
-  };
-
-  audit.meta!.timeEnd = Date.now();
-
-  return audit as Audit;
+  return await createAuditAsync(parseProjectPath());
 }
 
+/*** Serializes the current project audit as JSON. */
 export async function downloadAuditJsonAction(): Promise<{ data: string; filename: string }> {
   const audit = await getAuditAction();
   const jsonString = JSON.stringify(audit, null, 2);
@@ -47,6 +19,7 @@ export async function downloadAuditJsonAction(): Promise<{ data: string; filenam
   return { data: jsonString, filename };
 }
 
+/*** Serializes the current project audit as XML. */
 export async function downloadAuditXmlAction(): Promise<{ data: string; filename: string }> {
   const audit = await getAuditAction();
   const xmlString = js2xml({ audit }, { compact: true, spaces: 2 });
@@ -54,18 +27,3 @@ export async function downloadAuditXmlAction(): Promise<{ data: string; filename
 
   return { data: xmlString, filename };
 }
-
-interface AuditMeta {
-  timeEnd: number;
-  readonly timeStart: number;
-  readonly language: LanguageDetectionResult;
-  readonly projectName: string;
-}
-
-export interface Audit {
-  readonly evaluation: {
-    readonly cyclicPackages: PackageCycleDetail[];
-  };
-  readonly meta: AuditMeta;
-  readonly files: ParsedDirectory;
-}

package/src/app/globals.css

@@ -72,6 +72,4 @@ h2 {
 h3 {
   font-weight: bold;
   font-size: var(--text-sm);
-  margin-top: 1.6rem;
-  margin-left: 1.6rem;
 }

package/src/app/layout.tsx

@@ -1,8 +1,8 @@
-import type { Metadata } from 'next';
+import '@/app/globals.css';
 
+import type { Metadata } from 'next';
 import { Geist, Geist_Mono } from 'next/font/google';
 import { ThemeProvider } from 'next-themes';
-import '@/app/globals.css';
 
 const geistSans = Geist({ variable: '--font-geist-sans', subsets: ['latin'] });
 const geistMono = Geist_Mono({ variable: '--font-geist-mono', subsets: ['latin'] });
@@ -12,6 +12,7 @@ export const metadata: Metadata = {
   description: 'Package visualization',
 };
 
+/*** Renders the application root layout. */
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>

package/src/app/loading.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+
+import Loader from '@/components/Loader';
+
+/*** Keeps the centered loading indicator visible while the request-time project snapshot loads. */
+export default function Loading() {
+  return <Loader />;
+}

package/src/app/page.tsx

@@ -1,5 +1,19 @@
+import { connection } from 'next/server';
+
+import { loadProjectOverviewAsync } from '@/features/project-analysis/composition/loadProjectOverviewAsync';
 import HomeScreen from '@/screens/home/Home';
+import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+import { runProjectAnalysisActionAsync } from '@/utils/runProjectAnalysisActionAsync';
 
-export default function Home() {
-  return <HomeScreen />;
+/***
+ * Loads one overview per page request rather than starting analysis from client mount effects.
+ * @performance Keep this request-time read dynamic: build-time or persistent caching would hide
+ * source edits. Client Strict Mode rendering must not trigger another filesystem analysis.
+ */
+export default async function Home() {
+  await connection();
+  const project = await runProjectAnalysisActionAsync(() =>
+    loadProjectOverviewAsync(parseProjectPath())
+  );
+  return <HomeScreen project={project} />;
 }

package/src/app/utils/buildGraph.ts

@@ -1,119 +1,118 @@
-import type {
-  EdgeDataDefinition,
-  EdgeDefinition,
-  ElementsDefinition,
-  NodeDefinition,
-} from 'cytoscape';
+import type { Graph, GraphEdge, GraphNode } from '@ankhorage/graph';
+import { toCytoscapeElements } from '@ankhorage/graph-cytoscape';
+import type { ElementsDefinition } from 'cytoscape';
+
 import type { ParsedDirectory, ParsedFile } from '@/shared/types';
 
-/**
- * Builds a weighted dependency graph based on package-level imports.
- * - Adds intrinsic directory nodes (from folder structure)
- * - Aggregates edges (source pkg -> target pkg) with cumulative weight
- * - Adds vendor nodes for any edge endpoints not present as intrinsic nodes
- * - Sanitizes: skips empty package ids and self-edges
+/***
+ * Builds a weighted dependency graph and converts it through the canonical Cytoscape adapter.
  */
-export function buildGraph(dir: ParsedDirectory) {
-  /**
-   * Build graph (nodes/edges) recursively
-   */
-  function buildGraphRecursively(
-    currentDir: ParsedDirectory,
-    currentPath = '',
-    nodes: NodeDefinition[] = [],
-    edges: Map<string, EdgeDefinition> = new Map()
-  ) {
-    Object.keys(currentDir).forEach(key => {
-      const dirOrFile = (currentDir as Record<string, ParsedDirectory | ParsedFile>)[key];
-      const isDirectory = !(dirOrFile as ParsedFile)?.className;
-
-      // 1) Add directory as a node
-      if (isDirectory) {
-        const pkg = currentPath ? `${currentPath}.${key}` : key;
-
-        nodes.push({
-          data: {
-            id: pkg,
-            path: pkg,
-            parent: currentPath,
-            label: key,
-            name: key.split('.').pop() || key,
-            isIntrinsic: true,
-          },
-          group: 'nodes',
-        });
-
-        // Recurse into subdirectories
-        return buildGraphRecursively(dirOrFile as ParsedDirectory, pkg, nodes, edges);
-      }
-
-      // 2) Aggregate file imports as weighted package edges (package perspective)
-      const file = dirOrFile as ParsedFile;
-      const source = file.package?.trim();
-      if (!source) return; // skip empty/default package ids
-
-      const targets = (file.imports ?? [])
-        .map(imp => imp.pkg?.trim())
-        .filter((t): t is string => !!t);
-
-      targets.forEach(target => {
-        if (target === source) return; // skip self-edges at package level
-
-        const edgeId = `${source}->${target}`;
-        const existing = edges.get(edgeId);
-        const prev = (existing?.data as EdgeDataDefinitionWithWeight | undefined)?.weight ?? 0;
-        const weight: EdgeDataDefinitionWithWeight['weight'] = prev + 1;
-
-        const data: EdgeDataDefinitionWithWeight = { source, target, weight };
-        edges.set(edgeId, { data, group: 'edges' });
-      });
-    });
-
-    return { nodes, edges };
-  }
+export function buildGraph(dir: ParsedDirectory): ElementsDefinition {
+  const graph = buildCanonicalGraph(dir);
 
-  const rawElements: ElementsDefinitionWithEdgeMap = buildGraphRecursively(dir);
+  return toCytoscapeElements(graph, {
+    nodeClasses: node => (node.data.isIntrinsic === true ? undefined : 'isVendor'),
+  });
+}
 
-  // Add vendor packages (edge source/target not already in 'nodes')
-  rawElements.edges.forEach(({ data: { source, target } }) => {
-    [source, target].forEach(maybeNode => {
-      const id = String(maybeNode ?? '').trim();
-      if (!id) return; // don't create a node with empty id
+/*** Builds PKGViz package dependencies in the canonical Ankhorage graph model. */
+function buildCanonicalGraph(dir: ParsedDirectory): Graph<PackageNodeData, PackageEdgeData> {
+  const { nodes, edges } = buildGraphRecursively(dir);
 
-      // Node already defined while handling intrinsic directories
-      if (rawElements.nodes.find(node => node.data.id === id)) return;
+  for (const edge of edges.values()) {
+    for (const endpoint of [edge.source, edge.target]) {
+      if (nodes.some(node => node.id === endpoint)) continue;
 
-      // Grab the eventual parent for compound nodes
-      const parent = id.includes('.') ? id.split('.').slice(0, -1).join('.') : '';
+      const parent = endpoint.includes('.') ? endpoint.split('.').slice(0, -1).join('.') : '';
+      const name = endpoint.split('.').pop() || endpoint;
 
-      // Add vendor node: 'isIntrinsic' is not set (vendor package)
-      rawElements.nodes.push({
+      nodes.push({
+        id: endpoint,
         data: {
-          id: parent ? id.split('.').pop() : id,
-          label: id,
-          path: id,
+          label: endpoint,
+          path: endpoint,
           parent,
-          name: id.split('.').pop() || id,
+          name,
         },
-        group: 'nodes',
-        classes: 'isVendor',
       });
-    });
-  });
+    }
+  }
 
-  // Convert edges from Map (values) to EdgeDefinition[]
-  const elements: ElementsDefinition = {
-    nodes: rawElements.nodes,
-    edges: Array.from(rawElements.edges.values()),
+  return {
+    nodes,
+    edges: Array.from(edges.values()),
   };
+}
+
+/*** Recursively collects intrinsic package nodes and weighted dependency edges. */
+function buildGraphRecursively(
+  currentDir: ParsedDirectory,
+  currentPath = '',
+  nodes: GraphNode<PackageNodeData>[] = [],
+  edges = new Map<string, GraphEdge<PackageEdgeData>>()
+): CanonicalGraphAccumulator {
+  for (const key of Object.keys(currentDir)) {
+    const dirOrFile = (currentDir as Record<string, ParsedDirectory | ParsedFile>)[key];
+    const isDirectory = !(dirOrFile as ParsedFile)?.className;
+
+    if (isDirectory) {
+      const pkg = currentPath ? `${currentPath}.${key}` : key;
+
+      nodes.push({
+        id: pkg,
+        data: {
+          path: pkg,
+          parent: currentPath,
+          label: key,
+          name: key.split('.').pop() || key,
+          isIntrinsic: true,
+        },
+      });
+
+      buildGraphRecursively(dirOrFile as ParsedDirectory, pkg, nodes, edges);
+      continue;
+    }
+
+    const file = dirOrFile as ParsedFile;
+    const source = file.package?.trim();
+    if (!source) continue;
+
+    const targets = (file.imports ?? [])
+      .map(imp => imp.pkg?.trim())
+      .filter((target): target is string => Boolean(target));
+
+    for (const target of targets) {
+      if (target === source) continue;
+
+      const edgeId = `${source}->${target}`;
+      const existing = edges.get(edgeId);
+      const weight = (existing?.data.weight ?? 0) + 1;
 
-  return elements;
+      edges.set(edgeId, {
+        id: edgeId,
+        source,
+        target,
+        data: { weight },
+      });
+    }
+  }
+
+  return { nodes, edges };
 }
 
-interface EdgeDataDefinitionWithWeight extends EdgeDataDefinition {
-  weight: number;
+interface PackageNodeData extends Readonly<Record<string, unknown>> {
+  readonly path: string;
+  readonly parent: string;
+  readonly label: string;
+  readonly name: string;
+  readonly isIntrinsic?: boolean;
 }
-interface ElementsDefinitionWithEdgeMap {
-  readonly nodes: NodeDefinition[];
-  readonly edges: Map<string, EdgeDefinition>;
+
+interface PackageEdgeData extends Readonly<Record<string, unknown>> {
+  readonly weight: number;
+}
+
+interface CanonicalGraphAccumulator {
+  readonly nodes: GraphNode<PackageNodeData>[];
+  readonly edges: Map<string, GraphEdge<PackageEdgeData>>;
 }