pkgviz 0.7.7 → 0.8.0

package/src/app/utils/getParsedFileStructure.ts

@@ -1,26 +1,35 @@
 'use server';
-import { Language, type ParsedDirectory } from '@/shared/types';
-
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { toPosix } from '@/shared/utils/toPosix';
-import { detectLanguage } from '@/shared/utils/detectLanguage';
-import { parseJavaFile } from '@/app/utils/parser/java/parseJavaFile';
-import { parseFile as parseTypeScriptFile } from '@/app/utils/parser/typescript/parseFile';
+
+import {
+  readDirectoryWithinRoot,
+  resolveFileSystemPathWithinRoot,
+} from '@ankhorage/utility/node/fs';
+
 import { parseCppFile } from '@/app/utils/parser/cpp/parseCppFile';
-import { parsePythonFile } from '@/app/utils/parser/python/parseFile';
 import { parseDelphiFile } from '@/app/utils/parser/delphi/parseFile';
+import { parseJavaFile } from '@/app/utils/parser/java/parseJavaFile';
 import { parseKotlinFile } from '@/app/utils/parser/kotlin/parseFile';
-import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+import { parsePythonFile } from '@/app/utils/parser/python/parseFile';
+import { parseFile as parseTypeScriptFile } from '@/app/utils/parser/typescript/parseFile';
+import { analyzeDependencyImportsAsync } from '@/features/dependency-analysis/adapters/outbound/dependency-graph/analyzeDependencyImportsAsync';
 import { JAVA_ROOT } from '@/shared/constants';
+import { type ImportDefinition, Language, type ParsedDirectory } from '@/shared/types';
+import { parseProjectPath } from '@/shared/utils/parseProjectPath';
+import { toPosix } from '@/shared/utils/toPosix';
 
-/**
+import { inspectParserLanguageAsync } from './inspectParserLanguageAsync';
+
+/***
  * Returns resolved root
  */
-export async function resolveRoot(dir: string, detectedLanguage: Language) {
+async function resolveRoot(dir: string, detectedLanguage: Language) {
+  const projectRoot = resolveFileSystemPathWithinRoot(dir, '.', { allowRoot: true });
+
   switch (detectedLanguage) {
     case Language.Java: {
-      const javaRoot = toPosix(path.resolve(dir, JAVA_ROOT));
+      const javaRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, JAVA_ROOT));
       if (!existsSync(javaRoot)) {
         console.error('Failed to find:', JAVA_ROOT);
         throw new Error(`Invalid Java project structure. Missing ${JAVA_ROOT}`);
@@ -30,93 +39,91 @@ export async function resolveRoot(dir: string, detectedLanguage: Language) {
 
     case Language.TypeScript:
       // Normalize to an absolute project root
-      return toPosix(path.resolve(dir));
+      return toPosix(projectRoot);
 
     case Language.Cpp:
       // For C++, look for src directory or use project root
-      const cppSrcRoot = toPosix(path.resolve(dir, 'src'));
+      const cppSrcRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'src'));
       if (existsSync(cppSrcRoot)) {
         return cppSrcRoot;
       }
-      return toPosix(path.resolve(dir));
+      return toPosix(projectRoot);
 
     case Language.Python:
       // For Python, look for src directory or use project root
-      const pythonSrcRoot = toPosix(path.resolve(dir, 'src'));
+      const pythonSrcRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'src'));
       if (existsSync(pythonSrcRoot)) {
         return pythonSrcRoot;
       }
       // Also check for common Python app structure
-      const appRoot = toPosix(path.resolve(dir, 'app'));
+      const appRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'app'));
       if (existsSync(appRoot)) {
         return appRoot;
       }
-      return toPosix(path.resolve(dir));
+      return toPosix(projectRoot);
 
     case Language.Delphi:
       // For Delphi, look for common source directories
-      const delphiSrcRoot = toPosix(path.resolve(dir, 'src'));
+      const delphiSrcRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'src'));
       if (existsSync(delphiSrcRoot)) {
         return delphiSrcRoot;
       }
       // Also check for Source directory (common in Delphi projects)
-      const sourceRoot = toPosix(path.resolve(dir, 'Source'));
+      const sourceRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'Source'));
       if (existsSync(sourceRoot)) {
         return sourceRoot;
       }
-      return toPosix(path.resolve(dir));
+      return toPosix(projectRoot);
 
     case Language.Kotlin:
       // For Kotlin, look for src/main/kotlin directory (Gradle/Maven structure)
-      const kotlinSrcRoot = toPosix(path.resolve(dir, 'src/main/kotlin'));
+      const kotlinSrcRoot = toPosix(
+        resolveFileSystemPathWithinRoot(projectRoot, 'src/main/kotlin')
+      );
       if (existsSync(kotlinSrcRoot)) {
         return kotlinSrcRoot;
       }
       // Fallback to src directory
-      const kotlinAltSrcRoot = toPosix(path.resolve(dir, 'src'));
+      const kotlinAltSrcRoot = toPosix(resolveFileSystemPathWithinRoot(projectRoot, 'src'));
       if (existsSync(kotlinAltSrcRoot)) {
         return kotlinAltSrcRoot;
       }
-      return toPosix(path.resolve(dir));
+      return toPosix(projectRoot);
 
     default:
       throw new Error(`Invalid file structure for ${detectedLanguage}`);
   }
 }
 
-/**
+/***
  * Read directory recursively
  */
-export async function readDirRecursively(
+async function readDirRecursively(
   dir: string,
-  result: ParsedDirectory = {},
   projectRoot: string,
-  language: Language
+  language: Language,
+  analysisRoot: string,
+  importsByFile?: ReadonlyMap<string, readonly ImportDefinition[]>
 ): Promise<ParsedDirectory> {
-  const resolvedRoot = path.resolve(projectRoot);
-  const resolvedDir = path.resolve(dir);
+  const result: ParsedDirectory = Object.create(null);
 
-  // Validate dir is inside projectRoot (avoid path traversal / accidental escapes)
-  const relative = path.relative(resolvedRoot, resolvedDir);
-  if (relative.startsWith('..') || path.isAbsolute(relative)) {
-    throw new Error(`Path traversal detected: ${dir} is outside of project root ${projectRoot}`);
-  }
-
-  // 1. Read current directory
-  const entries = readdirSync(resolvedDir, { withFileTypes: true });
+  // 1. Read the current directory through the shared rooted-filesystem boundary.
+  const { entries, path: resolvedDir } = readDirectoryWithinRoot({
+    rootPath: projectRoot,
+    directoryPath: dir,
+  });
 
   const ignores = [
     '@types',
     '.cache',
     '.git',
     '.github',
-    '.meta',
+    '.generated',
     '.next',
-    '.vscode',
+    'dist',
     'coverage',
     'examples',
     'node_modules',
-    'packages',
     'test',
   ];
 
@@ -127,7 +134,13 @@ export async function readDirRecursively(
 
     // Directory: Recursively continue to read
     if (entry.isDirectory()) {
-      result[entry.name] = await readDirRecursively(fullPath, {}, projectRoot, language);
+      result[entry.name] = await readDirRecursively(
+        fullPath,
+        projectRoot,
+        language,
+        analysisRoot,
+        importsByFile
+      );
       continue;
     }
 
@@ -136,14 +149,24 @@ export async function readDirRecursively(
       // Java
       case Language.Java:
         if (entry.name.endsWith('.java')) {
-          result[entry.name] = await parseJavaFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical Java dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parseJavaFile(fullPath, projectRoot, imports);
         }
         break;
 
       // TypeScript
       case Language.TypeScript:
         if (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx')) {
-          result[entry.name] = await parseTypeScriptFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical TypeScript dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parseTypeScriptFile(fullPath, projectRoot, imports);
         }
         break;
 
@@ -157,14 +180,24 @@ export async function readDirRecursively(
           entry.name.endsWith('.hpp') ||
           entry.name.endsWith('.hxx')
         ) {
-          result[entry.name] = await parseCppFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical C++ dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parseCppFile(fullPath, projectRoot, imports);
         }
         break;
 
       // Python
       case Language.Python:
         if (entry.name.endsWith('.py')) {
-          result[entry.name] = await parsePythonFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical Python dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parsePythonFile(fullPath, projectRoot, imports);
         }
         break;
 
@@ -175,14 +208,24 @@ export async function readDirRecursively(
           entry.name.endsWith('.pp') ||
           entry.name.endsWith('.dpr')
         ) {
-          result[entry.name] = await parseDelphiFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical Delphi dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parseDelphiFile(fullPath, projectRoot, imports);
         }
         break;
 
       // Kotlin
       case Language.Kotlin:
         if (entry.name.endsWith('.kt') || entry.name.endsWith('.kts')) {
-          result[entry.name] = await parseKotlinFile(fullPath, projectRoot);
+          if (importsByFile === undefined) {
+            throw new Error('Missing canonical Kotlin dependency analysis.');
+          }
+          const relativeFile = toPosix(path.relative(projectRoot, fullPath));
+          const imports = importsByFile.get(relativeFile) ?? [];
+          result[entry.name] = await parseKotlinFile(fullPath, projectRoot, imports);
         }
         break;
     }
@@ -191,14 +234,15 @@ export async function readDirRecursively(
   return result;
 }
 
-/**
+/***
  * Entrypoint
  */
-export async function getParsedFileStructure() {
-  const projectPath = parseProjectPath();
-
+export async function getParsedFileStructure(
+  language?: Language,
+  projectPath: string = parseProjectPath()
+) {
   // 1. Detect language & filter non-supported
-  const detectedLanguage = (await detectLanguage(projectPath)).language;
+  const detectedLanguage = language ?? (await inspectParserLanguageAsync(projectPath)).language;
   console.log('1. Detected language:', detectedLanguage);
 
   if (
@@ -220,6 +264,36 @@ export async function getParsedFileStructure() {
   const rootDir = await resolveRoot(projectPath, detectedLanguage);
   console.log('2. rootDir:', rootDir);
 
+  const importsByFile =
+    detectedLanguage === Language.TypeScript
+      ? await analyzeDependencyImportsAsync(projectPath)
+      : detectedLanguage === Language.Java
+        ? await analyzeDependencyImportsAsync(projectPath, rootDir, 'specifier')
+        : detectedLanguage === Language.Kotlin
+          ? await analyzeDependencyImportsAsync(
+              projectPath,
+              rootDir,
+              'specifier',
+              'kotlin-standard-library'
+            )
+          : detectedLanguage === Language.Python
+            ? await analyzeDependencyImportsAsync(
+                projectPath,
+                rootDir,
+                'specifier',
+                'python-legacy'
+              )
+            : detectedLanguage === Language.Cpp
+              ? await analyzeDependencyImportsAsync(projectPath, rootDir, 'specifier')
+              : detectedLanguage === Language.Delphi
+                ? await analyzeDependencyImportsAsync(
+                    projectPath,
+                    rootDir,
+                    'specifier',
+                    'delphi-standard-library'
+                  )
+                : undefined;
+
   // 3. Read directory recursively (pass resolved root as both dir and projectRoot)
-  return await readDirRecursively(rootDir, {}, rootDir, detectedLanguage);
+  return await readDirRecursively(rootDir, rootDir, detectedLanguage, projectPath, importsByFile);
 }

package/src/app/utils/inspectParserLanguageAsync.ts

@@ -0,0 +1,39 @@
+import { inspectProjectAsync } from '@ankhorage/project-detector/node';
+
+import type { ParserSelection } from '../../types/parserSelection';
+import { selectParserLanguage } from './selectParserLanguage';
+
+const PROJECT_PATH_ERROR_CODES: ReadonlySet<string> = new Set(['EACCES', 'ENOENT', 'ENOTDIR']);
+
+/*** Inspect safely through the canonical detector, then apply pkgviz's parser selection policy. */
+export async function inspectParserLanguageAsync(projectPath: string): Promise<ParserSelection> {
+  try {
+    const inspection = await inspectProjectAsync(projectPath, {
+      excludeDirectories: ['@types', '.github', 'examples', 'test'],
+    });
+    if (!inspection.complete) {
+      throw new Error(
+        `Project inspection is incomplete: ${inspection.diagnostics.map(diagnostic => diagnostic.message).join('; ')}`
+      );
+    }
+    return selectParserLanguage(inspection.detection);
+  } catch (error) {
+    if (!isProjectPathUnavailableError(error)) throw error;
+
+    const projectPathError = new Error(`Invalid or unavailable project path: ${projectPath}`, {
+      cause: error,
+    });
+    projectPathError.name = 'ProjectPathUnavailableError';
+    throw projectPathError;
+  }
+}
+
+/*** Identify filesystem errors that mean the configured inspection root cannot be used. */
+function isProjectPathUnavailableError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    typeof error.code === 'string' &&
+    PROJECT_PATH_ERROR_CODES.has(error.code)
+  );
+}

package/src/app/utils/markCyclicPackages.ts

@@ -1,9 +1,13 @@
+import { findCyclePath, findCyclicComponents, type Graph } from '@ankhorage/graph';
 import type { ElementsDefinition } from 'cytoscape';
+
 import type { ParsedDirectory, ParsedFile } from '@/shared/types';
+import type { CycleEdgeEvidence, ImportEvidence, PackageCycleDetail } from '@/types/audit';
 
-/** Collect all files from your ParsedDirectory tree. */
+/*** Collect all files from your ParsedDirectory tree. */
 function collectFiles(root: ParsedDirectory): ParsedFile[] {
   const files: ParsedFile[] = [];
+  /*** Collects parsed files by traversing the parsed directory tree. */
   const walk = (dir: ParsedDirectory) => {
     for (const key in dir) {
       const entry = (dir as Record<string, unknown>)[key];
@@ -18,15 +22,15 @@ function collectFiles(root: ParsedDirectory): ParsedFile[] {
   return files;
 }
 
-/** Build per-edge evidence: key "from->to" → list of ImportEvidence. */
+/*** Build per-edge evidence: key "from->to" → list of ImportEvidence. */
 function buildEdgeEvidence(dir: ParsedDirectory): Map<string, ImportEvidence[]> {
   const files = collectFiles(dir);
   const map = new Map<string, ImportEvidence[]>();
 
   for (const f of files) {
-    const from = f.package as TUniquePackageName;
+    const from = f.package;
     for (const imp of f.imports ?? []) {
-      const to = imp.pkg as TUniquePackageName;
+      const to = imp.pkg;
       if (!to || to === from) continue;
       const key = `${from}->${to}`;
       if (!map.has(key)) map.set(key, []);
@@ -41,16 +45,16 @@ function buildEdgeEvidence(dir: ParsedDirectory): Map<string, ImportEvidence[]>
   return map;
 }
 
-/** Convert ElementsDefinition (from buildGraph) to adjacency map. */
+/*** Convert ElementsDefinition (from buildGraph) to adjacency map. */
 function elementsToAdj(elements: ElementsDefinition) {
   const adj = new Map<TUniquePackageName, Set<TUniquePackageName>>();
   for (const n of elements.nodes) {
-    const id = String(n.data.id) as TUniquePackageName;
+    const id = String(n.data.id);
     if (!adj.has(id)) adj.set(id, new Set());
   }
   for (const e of elements.edges) {
-    const s = String(e.data.source) as TUniquePackageName;
-    const t = String(e.data.target) as TUniquePackageName;
+    const s = String(e.data.source);
+    const t = String(e.data.target);
     if (!adj.has(s)) adj.set(s, new Set());
     if (!adj.has(t)) adj.set(t, new Set());
     adj.get(s)!.add(t);
@@ -58,79 +62,24 @@ function elementsToAdj(elements: ElementsDefinition) {
   return adj;
 }
 
-/** Tarjan SCC on adjacency. */
-function tarjanSCC(
-  graph: Map<TUniquePackageName, Set<TUniquePackageName>>
-): TUniquePackageName[][] {
-  let index = 0;
-  const idx = new Map<TUniquePackageName, number>();
-  const low = new Map<TUniquePackageName, number>();
-  const stack: TUniquePackageName[] = [];
-  const onStack = new Set<TUniquePackageName>();
-  const out: TUniquePackageName[][] = [];
-
-  function strong(v: TUniquePackageName) {
-    idx.set(v, index);
-    low.set(v, index);
-    index++;
-    stack.push(v);
-    onStack.add(v);
-
-    for (const w of graph.get(v) ?? []) {
-      if (!idx.has(w)) {
-        strong(w);
-        low.set(v, Math.min(low.get(v)!, low.get(w)!));
-      } else if (onStack.has(w)) {
-        low.set(v, Math.min(low.get(v)!, idx.get(w)!));
-      }
-    }
-
-    if (low.get(v) === idx.get(v)) {
-      const comp: TUniquePackageName[] = [];
-      let w: TUniquePackageName;
-      do {
-        w = stack.pop()!;
-        onStack.delete(w);
-        comp.push(w);
-      } while (w !== v);
-      out.push(comp);
-    }
-  }
-
-  for (const v of graph.keys()) if (!idx.has(v)) strong(v);
-  return out;
-}
-
-/** Find one simple cycle ordering inside a given SCC. */
-function findOneCycleInScc(
-  graph: Map<TUniquePackageName, Set<TUniquePackageName>>,
-  sccSet: Set<TUniquePackageName>
-): TUniquePackageName[] | null {
-  const nodes = Array.from(sccSet);
-  for (const start of nodes) {
-    const path: TUniquePackageName[] = [];
-    const seen = new Set<TUniquePackageName>();
-    function dfs(v: TUniquePackageName): TUniquePackageName[] | null {
-      path.push(v);
-      seen.add(v);
-      for (const w of graph.get(v) ?? []) {
-        if (!sccSet.has(w)) continue;
-        if (w === start && path.length > 1) return [...path, start];
-        if (!seen.has(w)) {
-          const r = dfs(w);
-          if (r) return r;
-        }
-      }
-      path.pop();
-      return null;
-    }
-    const cyc = dfs(start);
-    if (cyc) return cyc;
-  }
-  return null;
+/*** Convert adjacency to the canonical Ankhorage graph model for shared algorithms. */
+function adjacencyToGraph(
+  adjacency: ReadonlyMap<TUniquePackageName, ReadonlySet<TUniquePackageName>>
+): Graph<undefined, undefined> {
+  return {
+    nodes: Array.from(adjacency.keys(), id => ({ id, data: undefined })),
+    edges: Array.from(adjacency.entries()).flatMap(([source, targets]) =>
+      Array.from(targets, target => ({
+        id: `${source}->${target}`,
+        source,
+        target,
+        data: undefined,
+      }))
+    ),
+  };
 }
 
-/**
+/***
  * High-level API: build graph via `buildGraph`, detect package cycles,
  * and attach **member evidence** (files/imports) per cycle edge.
  */
@@ -143,107 +92,36 @@ export function getPackageCyclesWithMembers(
   graph: ElementsDefinition; // for convenience (already built)
 } {
   const adj = elementsToAdj(graph);
-  const sccs = tarjanSCC(adj);
+  const canonicalGraph = adjacencyToGraph(adj);
+  const sccs = findCyclicComponents(canonicalGraph);
   const evidence = buildEdgeEvidence(dir);
 
   const cycles: PackageCycleDetail[] = [];
   const packageSet = new Set<TUniquePackageName>();
 
   for (const scc of sccs) {
-    const selfLoop = scc.length === 1 && (adj.get(scc[0])?.has(scc[0]) ?? false);
-    if (scc.length > 1 || selfLoop) {
-      scc.forEach(p => packageSet.add(p));
-      const sccSet = new Set(scc);
-      const cycle = findOneCycleInScc(adj, sccSet) ?? [...scc, scc[0]];
+    scc.forEach(p => packageSet.add(p));
+    const cycle = [...(findCyclePath(canonicalGraph, scc) ?? [...scc, scc[0]])];
 
-      const edges: CycleEdgeEvidence[] = [];
-      for (let i = 0; i < cycle.length - 1; i++) {
-        const from = cycle[i];
-        const to = cycle[i + 1];
-        const key = `${from}->${to}`;
-        edges.push({
-          from,
-          to,
-          via: evidence.get(key) ?? [],
-        });
-      }
-
-      cycles.push({ packages: cycle, edges });
+    const edges: CycleEdgeEvidence[] = [];
+    for (let i = 0; i < cycle.length - 1; i++) {
+      const from = cycle[i];
+      const to = cycle[i + 1];
+      const key = `${from}->${to}`;
+      edges.push({
+        from,
+        to,
+        via: evidence.get(key) ?? [],
+      });
     }
-  }
 
-  return { cycles, packageSet, graph };
-}
-
-/**
- * Annotate Cytoscape nodes:
- *  - adds class "packageCycle" for cyclic packages
- *  - sets data.packageCycle (boolean)
- *  - sets data.cycleEvidence (edges where this pkg is the "from" side)
- */
-export function markCyclicPackagesWithEvidence(
-  elements: ElementsDefinition,
-  dir: ParsedDirectory
-): ElementsDefinition {
-  const { cycles, packageSet } = getPackageCyclesWithMembers(dir, elements);
-
-  // pkg → list of outgoing cycle edges (evidence)
-  const pkgToEdges = new Map<TUniquePackageName, CycleEdgeEvidence[]>();
-
-  // Track cycle edges by (from → to) for quick lookup when mapping Cytoscape edges
-  const cycleEdgeKeys = new Set<string>();
-
-  for (const c of cycles) {
-    for (const e of c.edges) {
-      if (!pkgToEdges.has(e.from)) pkgToEdges.set(e.from, []);
-      pkgToEdges.get(e.from)!.push(e);
-      cycleEdgeKeys.add(`${e.from}→${e.to}`);
-    }
+    cycles.push({ packages: cycle, edges });
   }
 
-  const nodes = (elements.nodes ?? []).map(n => {
-    const id = String(n.data.id) as TUniquePackageName;
-    const isCyclic = packageSet.has(id);
-    const existing = n.classes ? String(n.classes) : '';
-    const classes = isCyclic ? (existing ? `${existing} packageCycle` : 'packageCycle') : existing;
-
-    return {
-      ...n,
-      classes,
-      data: {
-        ...n.data,
-        packageCycle: isCyclic,
-        cycleEvidence: isCyclic ? (pkgToEdges.get(id) ?? []) : undefined,
-      },
-    };
-  });
-
-  const edges = (elements.edges ?? []).map(e => {
-    const source = String(e.data.source) as TUniquePackageName;
-    const target = String(e.data.target) as TUniquePackageName;
-    const isCycleEdge = cycleEdgeKeys.has(`${source}→${target}`);
-
-    const existing = e.classes ? String(e.classes) : '';
-    const classes = isCycleEdge
-      ? existing
-        ? `${existing} packageCycle`
-        : 'packageCycle'
-      : existing;
-
-    return {
-      ...e,
-      classes,
-      data: {
-        ...e.data,
-        packageCycle: isCycleEdge,
-      },
-    };
-  });
-
-  return { ...elements, nodes, edges };
+  return { cycles, packageSet, graph };
 }
 
-/**
+/***
  * Convenience that only returns the set of cyclic packages (no evidence)
  */
 export function getCyclicPackageSet(
@@ -255,21 +133,3 @@ export function getCyclicPackageSet(
 }
 
 type TUniquePackageName = string;
-
-interface ImportEvidence {
-  readonly filePath: string; // ParsedFile.path (relative to project)
-  readonly fileClass: string; // ParsedFile.className
-  readonly importName: string; // IJavaImport.name
-  readonly isIntrinsic?: boolean; // IJavaImport.isIntrinsic
-}
-
-interface CycleEdgeEvidence {
-  readonly from: TUniquePackageName;
-  readonly to: TUniquePackageName;
-  readonly via: ImportEvidence[]; // files in `from` that import `to`
-}
-
-export interface PackageCycleDetail {
-  readonly packages: TUniquePackageName[]; // ordered cycle incl. closing node, e.g. ["A","B","A"]
-  readonly edges: CycleEdgeEvidence[]; // evidence aligned with packages[i] -> packages[i+1]
-}