nest-graph-inspector 0.3.0 → 0.5.0

package/src/nest-graph-inspector.setup.js

@@ -14,6 +14,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 var NestGraphInspectorSetup_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NestGraphInspectorSetup = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const common_1 = require("@nestjs/common");
 const core_1 = require("@nestjs/core");
 const nest_graph_inspector_config_1 = require("./nest-graph-inspector.config");
@@ -22,6 +24,7 @@ const http_output_adapter_1 = require("./adapters/http-output.adapter");
 const file_output_adapter_1 = require("./adapters/file-output.adapter");
 const json_output_adapter_1 = require("./adapters/json-output.adapter");
 const viewer_output_adapter_1 = require("./adapters/viewer-output.adapter");
+const ts_morph_1 = require("ts-morph");
 let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspectorSetup {
     options;
     modulesContainer;
@@ -35,6 +38,7 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
     ignoreImport;
     nestCoreModuleName;
     nestCoreProviders;
+    tsMorphProject = this.createTsMorphProject();
     constructor(options, modulesContainer, httpOutputAdapter, fileOutputAdapter, jsonOutputAdapter, viewerOutputAdapter) {
         this.options = options;
         this.modulesContainer = modulesContainer;
@@ -65,30 +69,70 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         ];
     }
     async onModuleInit() {
-        const rootModuleClass = this.options.rootModule;
-        const moduleMap = rootModuleClass
-            ? this.buildModuleMap(rootModuleClass)
-            : this.buildModuleMapFromAutoDetect();
-        if (!this.options.outputs?.length) {
+        await this.inspectAndPublishGraph();
+    }
+    async inspectAndPublishGraph() {
+        if (!this.hasOutput) {
             return;
         }
-        const graphOutput = this.enrichModuleMap(moduleMap);
-        await Promise.all(this.options.outputs.map(async (output) => {
-            output = this.withDefaultOutputOptions(output);
-            const adapter = this.outputAdapters[output.type];
-            if (!adapter) {
-                this.logger.warn(`Unsupported output type: ${output.type}`);
-                return;
-            }
-            try {
-                const { message } = await adapter.execute(graphOutput, output);
-                this.logger.debug(message);
-            }
-            catch (err) {
-                this.logger.error(`Failed to execute output adapter for type ${output.type}`, err);
-            }
+        const rootModule = this.getRootModule();
+        const moduleTree = this.getModuleTree(rootModule);
+        await this.publishModuleTree(moduleTree);
+    }
+    get hasOutput() {
+        return !!this.options.outputs?.length;
+    }
+    getRootModule() {
+        const rootModuleClass = this.options.rootModule;
+        return rootModuleClass
+            ? this.getRootModuleFromClass(rootModuleClass)
+            : this.findRootModule();
+    }
+    getRootModuleFromClass(rootModuleClass) {
+        const root = [...this.modulesContainer.values()].find((m) => m.metatype === rootModuleClass);
+        if (!root) {
+            throw new Error(`Root module not found: ${rootModuleClass.name}`);
+        }
+        return root;
+    }
+    getModuleTree(rootModule) {
+        const moduleTree = this.resolveModuleTree(rootModule);
+        this.resolveModuleMembers(moduleTree);
+        this.appendNestCoreModule(moduleTree);
+        return moduleTree;
+    }
+    async publishModuleTree(moduleTree) {
+        const moduleMap = this.createModuleMapFromModuleTree(moduleTree);
+        const graphOutput = this.createGraphOutput(moduleMap);
+        const outputs = this.prepareOutputs();
+        await this.publishOutputs({ graphOutput, outputs });
+    }
+    createGraphOutput(moduleMap) {
+        return this.enrichModuleMap(moduleMap);
+    }
+    prepareOutputs() {
+        return this.options.outputs ?? [];
+    }
+    async publishOutputs(param) {
+        await Promise.all(param.outputs.map(async (output) => {
+            await this.publishSingleOutput(param.graphOutput, output);
         }));
     }
+    async publishSingleOutput(graphOutput, output) {
+        output = this.withDefaultOutputOptions(output);
+        const adapter = this.outputAdapters[output.type];
+        if (!adapter) {
+            this.logger.warn(`Unsupported output type: ${output.type}`);
+            return;
+        }
+        try {
+            const { message } = await adapter.execute(graphOutput, output);
+            this.logger.debug(message);
+        }
+        catch (err) {
+            this.logger.error(`Failed to execute output adapter for type ${output.type}`, err);
+        }
+    }
     withDefaultOutputOptions(output) {
         if (output.type !== 'viewer') {
             return output;
@@ -107,37 +151,19 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
     }
     buildModuleMapFromAutoDetect() {
         const root = this.findRootModule();
-        return this.buildModuleMapFromRef(root);
+        const moduleTree = this.getModuleTree(root);
+        return this.createModuleMapFromModuleTree(moduleTree);
     }
     buildModuleMap(rootModuleClass) {
-        const root = [...this.modulesContainer.values()].find((m) => m.metatype === rootModuleClass);
-        if (!root) {
-            throw new Error(`Root module not found: ${rootModuleClass.name}`);
-        }
-        return this.buildModuleMapFromRef(root);
+        const root = this.getRootModuleFromClass(rootModuleClass);
+        const moduleTree = this.getModuleTree(root);
+        return this.createModuleMapFromModuleTree(moduleTree);
     }
-    buildModuleMapFromRef(root) {
-        const reachable = this.collectReachableModules(root, new Set());
-        const modules = {};
-        for (const moduleRef of reachable) {
-            const moduleName = this.moduleName(moduleRef);
-            if (this.ignoreImport.includes(moduleName)) {
-                continue;
-            }
-            modules[moduleName] = {
-                imports: this.extractImports(moduleRef),
-                exports: this.extractExports(moduleRef),
-                providers: this.extractProviders(moduleRef, moduleName),
-                controllers: this.extractControllers(moduleRef, moduleName),
-            };
-        }
-        const usedNestCoreProviders = this.findUsedNestCoreProviders(modules);
-        if (usedNestCoreProviders.length > 0) {
-            modules[this.nestCoreModuleName] = this.buildNestCoreModule(usedNestCoreProviders);
-        }
+    createModuleMapFromModuleTree(moduleTree) {
+        const modules = this.flattenModuleTree(moduleTree);
         return {
-            version: '2',
-            root: this.moduleName(root),
+            version: '3',
+            root: moduleTree.name,
             modules,
         };
     }
@@ -156,21 +182,69 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         }
         throw new Error('Could not auto-detect root module. No module imports NestGraphInspectorModule.');
     }
-    buildNestCoreModule(usedProviders) {
+    resolveModuleTree(moduleRef, visited = new Set()) {
+        if (visited.has(moduleRef)) {
+            return this.createModuleTreeReference(moduleRef);
+        }
+        visited.add(moduleRef);
+        return {
+            name: this.moduleName(moduleRef),
+            jsdoc: this.extractModuleJsDoc(moduleRef),
+            moduleRef,
+            imports: [],
+            exports: [],
+            providers: [],
+            controllers: [],
+            children: [...moduleRef.imports.values()]
+                .filter((childModule) => !this.shouldIgnoreModule(childModule))
+                .map((childModule) => this.resolveModuleTree(childModule, visited)),
+        };
+    }
+    createModuleTreeReference(moduleRef) {
         return {
+            name: this.moduleName(moduleRef),
+            jsdoc: this.extractModuleJsDoc(moduleRef),
+            moduleRef,
+            imports: [],
+            exports: [],
+            providers: [],
+            controllers: [],
+            children: [],
+        };
+    }
+    resolveModuleMembers(moduleTree) {
+        this.walkModuleTree(moduleTree, (node) => {
+            if (!node.moduleRef) {
+                return;
+            }
+            node.imports = node.children.map((child) => child.name);
+            node.exports = this.extractExports(node.moduleRef);
+            node.providers = this.extractProviders(node.moduleRef, node.name);
+            node.controllers = this.extractControllers(node.moduleRef, node.name);
+        });
+    }
+    appendNestCoreModule(moduleTree) {
+        const usedProviders = this.findUsedNestCoreProvidersFromTree(moduleTree);
+        if (!usedProviders.length) {
+            return;
+        }
+        moduleTree.children.push({
+            name: this.nestCoreModuleName,
+            moduleRef: null,
             imports: [],
             exports: [...usedProviders],
-            providers: usedProviders.map((providerName) => ({
-                name: providerName,
+            providers: usedProviders.map((name) => ({
+                name,
                 dependencies: [],
             })),
             controllers: [],
-        };
+            children: [],
+        });
     }
-    findUsedNestCoreProviders(modules) {
+    findUsedNestCoreProvidersFromTree(moduleTree) {
         const usedProviders = new Set();
-        for (const moduleData of Object.values(modules)) {
-            for (const provider of moduleData.providers) {
+        this.walkModuleTree(moduleTree, (node) => {
+            for (const provider of node.providers) {
                 for (const dependencyName of provider.dependencies) {
                     const nestCoreProviderName = this.extractNestCoreProviderName(dependencyName);
                     if (nestCoreProviderName) {
@@ -178,7 +252,7 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
                     }
                 }
             }
-            for (const controller of moduleData.controllers) {
+            for (const controller of node.controllers) {
                 for (const dependencyName of controller.dependencies) {
                     const nestCoreProviderName = this.extractNestCoreProviderName(dependencyName);
                     if (nestCoreProviderName) {
@@ -186,9 +260,34 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
                     }
                 }
             }
-        }
+        });
         return this.nestCoreProviders.filter((providerName) => usedProviders.has(providerName));
     }
+    flattenModuleTree(moduleTree) {
+        const modules = {};
+        this.walkModuleTree(moduleTree, (node) => {
+            if (modules[node.name] || this.ignoreImport.includes(node.name)) {
+                return;
+            }
+            modules[node.name] = {
+                ...(node.jsdoc ? { jsdoc: node.jsdoc } : {}),
+                imports: node.imports,
+                exports: node.exports,
+                providers: node.providers,
+                controllers: node.controllers,
+            };
+        });
+        return modules;
+    }
+    walkModuleTree(moduleTree, visit) {
+        visit(moduleTree);
+        for (const child of moduleTree.children) {
+            this.walkModuleTree(child, visit);
+        }
+    }
+    shouldIgnoreModule(moduleRef) {
+        return this.ignoreImport.includes(this.moduleName(moduleRef));
+    }
     extractNestCoreProviderName(dependencyName) {
         const prefix = `${this.nestCoreModuleName}:`;
         if (!dependencyName.startsWith(prefix)) {
@@ -203,16 +302,6 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         }
         return providerName;
     }
-    collectReachableModules(root, visited) {
-        if (visited.has(root))
-            return [];
-        visited.add(root);
-        const result = [root];
-        for (const imported of root.imports.values()) {
-            result.push(...this.collectReachableModules(imported, visited));
-        }
-        return result;
-    }
     extractImports(moduleRef) {
         return [...moduleRef.imports.values()]
             .map((importedModuleRef) => this.moduleName(importedModuleRef))
@@ -224,59 +313,116 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
             .filter((exportName) => !!exportName && !this.ignoreProvider.includes(exportName));
     }
     extractProviders(moduleRef, moduleName) {
-        return [...moduleRef.providers.values()]
-            .map((wrapper) => this.extractProvider(wrapper, moduleName, moduleRef))
-            .filter((provider) => !!provider);
+        return this.extractModuleMembers({
+            wrappers: moduleRef.providers.values(),
+            moduleRef,
+            extract: (wrapper) => this.extractModuleMember({
+                wrapper,
+                moduleRef,
+                shouldIgnore: (name) => this.ignoreProvider.includes(name),
+            }),
+            shouldSkip: (provider) => provider.name === moduleName,
+        });
     }
     extractControllers(moduleRef, moduleName) {
-        return [...moduleRef.controllers.values()]
-            .map((wrapper) => this.extractController(wrapper, moduleName, moduleRef))
-            .filter((controller) => !!controller);
+        return this.extractModuleMembers({
+            wrappers: moduleRef.controllers.values(),
+            moduleRef,
+            extract: (wrapper) => this.extractModuleMember({ wrapper, moduleRef }),
+        });
     }
-    extractProvider(wrapper, moduleName, moduleRef) {
-        const name = this.wrapperName(wrapper);
-        if (!name || this.ignoreProvider.includes(name) || name === moduleName) {
+    extractModuleMembers(param) {
+        return [...param.wrappers].reduce((items, wrapper) => {
+            const executableWrapper = wrapper;
+            const item = param.extract(executableWrapper, param.moduleRef);
+            if (item) {
+                if (param.shouldSkip?.(item)) {
+                    return items;
+                }
+                items.push(item);
+            }
+            return items;
+        }, []);
+    }
+    extractModuleMember(param) {
+        const { wrapper, moduleRef, shouldIgnore = () => false } = param;
+        const name = this.wrapperClassName(wrapper) || this.tokenName(wrapper.token);
+        if (!name || shouldIgnore(name)) {
             return null;
         }
+        const jsdoc = this.extractClassJsDoc(wrapper);
         return {
             name,
+            ...(jsdoc ? { jsdoc } : {}),
             dependencies: this.extractDependencies(wrapper, moduleRef),
         };
     }
-    extractController(wrapper, moduleName, moduleRef) {
-        const name = this.wrapperName(wrapper);
-        if (!name) {
-            return null;
+    createTsMorphProject() {
+        const tsConfigFilePath = (0, node_path_1.join)(process.cwd(), 'tsconfig.json');
+        if (!(0, node_fs_1.existsSync)(tsConfigFilePath)) {
+            this.logger.warn(`Could not find tsconfig.json at ${tsConfigFilePath}; JSDoc metadata will be skipped.`);
+            return new ts_morph_1.Project();
         }
-        return {
-            name,
-            dependencies: this.extractDependencies(wrapper, moduleRef),
-        };
+        return new ts_morph_1.Project({
+            tsConfigFilePath,
+            skipAddingFilesFromTsConfig: false,
+        });
+    }
+    extractModuleJsDoc(moduleRef) {
+        return moduleRef.metatype
+            ? this.extractClassJsDocByName(moduleRef.metatype.name)
+            : undefined;
+    }
+    extractClassJsDoc(wrapper) {
+        const className = this.wrapperClassName(wrapper);
+        return className ? this.extractClassJsDocByName(className) : undefined;
+    }
+    extractClassJsDocByName(className) {
+        const targetClass = this.tsMorphProject
+            .getSourceFiles()
+            .flatMap((sourceFile) => sourceFile.getClasses())
+            .find((classDeclaration) => classDeclaration.getName() === className);
+        return targetClass
+            ?.getJsDocs()
+            .map((doc) => doc.getCommentText())
+            .filter((comment) => !!comment)
+            .join('\n');
+    }
+    wrapperClassName(wrapper) {
+        if (wrapper.metatype?.name) {
+            return wrapper.metatype.name;
+        }
+        const instance = wrapper.instance;
+        if (instance &&
+            (typeof instance === 'object' || typeof instance === 'function')) {
+            return instance.constructor?.name ?? null;
+        }
+        return null;
     }
     extractDependencies(wrapper, moduleRef) {
         const dependencies = new Set();
         if (Array.isArray(wrapper?.inject)) {
             for (const token of wrapper.inject) {
-                const dependencyName = this.resolveDependencyName(token, moduleRef);
+                const dependencyName = this.resolveDependencyName(this.resolveInjectionToken(token), moduleRef);
                 if (dependencyName) {
                     dependencies.add(dependencyName);
                 }
             }
         }
-        const ctorDeps = wrapper?.getCtorMetadata?.() ?? [];
+        const ctorDeps = wrapper.getCtorMetadata?.() ?? [];
         for (const depWrapper of ctorDeps) {
             if (depWrapper) {
-                const dependencyName = this.resolveDependencyName(depWrapper.token ?? depWrapper.name, moduleRef);
+                const dependencyName = this.resolveDependencyName(depWrapper.token, moduleRef);
                 if (dependencyName && dependencyName !== 'Object') {
                     dependencies.add(dependencyName);
                 }
             }
         }
-        const propertyDeps = wrapper?.getPropertiesMetadata?.() ?? [];
+        const propertyDeps = wrapper.getPropertiesMetadata?.() ?? [];
         for (const propertyDep of propertyDeps) {
             const depWrapper = propertyDep?.wrapper;
             if (depWrapper) {
-                const dependencyName = this.resolveDependencyName(depWrapper.token ?? depWrapper.name, moduleRef);
+                const dependencyName = this.resolveDependencyName(depWrapper.token, moduleRef);
                 if (dependencyName && dependencyName !== 'Object') {
                     dependencies.add(dependencyName);
                 }
@@ -284,6 +430,12 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         }
         return [...dependencies];
     }
+    resolveInjectionToken(token) {
+        if (typeof token === 'object' && token !== null && 'token' in token) {
+            return token.token;
+        }
+        return token;
+    }
     resolveDependencyName(token, moduleRef) {
         const tokenName = this.tokenName(token);
         if (!tokenName) {
@@ -313,7 +465,14 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
             if (!this.isSameProviderToken(wrapper, token)) {
                 continue;
             }
-            const providerName = this.wrapperName(wrapper);
+            const providerInstance = wrapper.instance &&
+                (typeof wrapper.instance === 'object' ||
+                    typeof wrapper.instance === 'function')
+                ? wrapper.instance
+                : null;
+            const providerName = wrapper.metatype?.name ||
+                providerInstance?.constructor?.name ||
+                this.tokenName(wrapper.token);
             if (!providerName) {
                 return null;
             }
@@ -331,7 +490,9 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         if (wrapper?.metatype === token) {
             return true;
         }
-        if (wrapper?.instance?.constructor === token) {
+        if (wrapper.instance &&
+            typeof wrapper.instance === 'object' &&
+            wrapper.instance.constructor === token) {
             return true;
         }
         return false;
@@ -342,15 +503,12 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
             .filter((exportName) => !!exportName));
     }
     exportName(exportedItem) {
-        return (this.wrapperName(exportedItem) ||
-            this.tokenName(exportedItem?.token || exportedItem));
+        return this.tokenName(exportedItem);
     }
     isExportedProviderToken(moduleRef, token) {
         const tokenName = this.tokenName(token);
         for (const exportedItem of moduleRef.exports.values()) {
-            if (exportedItem === token ||
-                exportedItem?.token === token ||
-                exportedItem?.metatype === token) {
+            if (exportedItem === token) {
                 return true;
             }
             if (tokenName && this.exportName(exportedItem) === tokenName) {
@@ -377,12 +535,6 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
             this.tokenName(moduleRef.token) ||
             'AnonymousModule');
     }
-    wrapperName(wrapper) {
-        return (wrapper?.metatype?.name ||
-            wrapper?.instance?.constructor?.name ||
-            this.tokenName(wrapper?.token) ||
-            null);
-    }
     tokenName(token) {
         if (!token)
             return null;
@@ -392,7 +544,7 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
             return token.toString();
         if (typeof token === 'function')
             return token.name;
-        return String(token);
+        return null;
     }
     enrichModuleMap(moduleMap) {
         if (!moduleMap.modules) {
@@ -415,8 +567,199 @@ let NestGraphInspectorSetup = NestGraphInspectorSetup_1 = class NestGraphInspect
         return {
             ...moduleMap,
             modules: enrichedModules,
+            cycles: this.findGraphCycles(enrichedModules),
+        };
+    }
+    findGraphCycles(modules) {
+        let nextId = 1;
+        const nextCycleId = () => nextId++;
+        return {
+            modules: this.findModuleCycles(modules, nextCycleId),
+            ...this.findDependencyCycles(modules, nextCycleId),
+        };
+    }
+    findModuleCycles(modules, nextCycleId) {
+        const graph = this.createGraph(Object.keys(modules));
+        for (const [moduleName, moduleData] of Object.entries(modules)) {
+            for (const importedModuleName of moduleData.imports) {
+                if (modules[importedModuleName]) {
+                    graph.get(moduleName)?.add(importedModuleName);
+                }
+            }
+        }
+        return this.findCycles(graph, nextCycleId);
+    }
+    findDependencyCycles(modules, nextCycleId) {
+        const nodes = new Map();
+        for (const [moduleName, moduleData] of Object.entries(modules)) {
+            for (const provider of moduleData.providers) {
+                const key = this.dependencyNodeKey(moduleName, provider.name);
+                nodes.set(key, {
+                    key,
+                    kind: 'provider',
+                    moduleName,
+                    name: provider.name,
+                });
+            }
+            for (const controller of moduleData.controllers) {
+                const key = this.dependencyNodeKey(moduleName, controller.name);
+                nodes.set(key, {
+                    key,
+                    kind: 'controller',
+                    moduleName,
+                    name: controller.name,
+                });
+            }
+        }
+        const graph = this.createGraph([...nodes.keys()]);
+        for (const [moduleName, moduleData] of Object.entries(modules)) {
+            for (const provider of moduleData.providers) {
+                this.addDependencyEdges(graph, this.dependencyNodeKey(moduleName, provider.name), provider.dependencies, nodes);
+            }
+            for (const controller of moduleData.controllers) {
+                this.addDependencyEdges(graph, this.dependencyNodeKey(moduleName, controller.name), controller.dependencies, nodes);
+            }
+        }
+        const cycles = this.findCycles(graph, nextCycleId);
+        return {
+            providers: cycles
+                .filter((cycle) => nodes.get(cycle.from)?.kind === 'provider')
+                .map((cycle) => this.toProviderCycle(cycle, nodes)),
+            controllers: cycles.filter((cycle) => nodes.get(cycle.from)?.kind === 'controller'),
+        };
+    }
+    addDependencyEdges(graph, sourceKey, dependencies, nodes) {
+        const sourceEdges = graph.get(sourceKey);
+        if (!sourceEdges) {
+            return;
+        }
+        for (const dependency of dependencies) {
+            const targetKey = this.dependencyNodeKey(dependency.providedBy.name, dependency.token);
+            if (nodes.has(targetKey)) {
+                sourceEdges.add(targetKey);
+            }
+        }
+    }
+    createGraph(keys) {
+        const graph = new Map();
+        for (const key of keys) {
+            graph.set(key, new Set());
+        }
+        return graph;
+    }
+    findCycles(graph, nextCycleId) {
+        const cycles = [];
+        const seenCycleKeys = new Set();
+        const reachableKeys = new Map();
+        for (const source of graph.keys()) {
+            reachableKeys.set(source, this.findReachableKeys(source, graph));
+        }
+        for (const [source, targets] of graph) {
+            for (const target of targets) {
+                if (source !== target && !reachableKeys.get(target)?.has(source)) {
+                    continue;
+                }
+                const path = source === target
+                    ? [source, source]
+                    : [source, ...this.findPath(target, source, graph)];
+                const cycleKey = this.getCanonicalCycleKey(path);
+                if (seenCycleKeys.has(cycleKey)) {
+                    continue;
+                }
+                seenCycleKeys.add(cycleKey);
+                cycles.push({
+                    id: nextCycleId(),
+                    from: source,
+                    to: target,
+                    type: this.getCycleType(source, target, graph),
+                    path,
+                });
+            }
+        }
+        return cycles;
+    }
+    getCanonicalCycleKey(path) {
+        const cyclePath = path.slice(0, -1);
+        if (cyclePath.length <= 1) {
+            return cyclePath.join('->');
+        }
+        const rotations = cyclePath.map((_, index) => [
+            ...cyclePath.slice(index),
+            ...cyclePath.slice(0, index),
+        ]);
+        return rotations
+            .map((rotation) => rotation.join('->'))
+            .sort((a, b) => a.localeCompare(b))[0];
+    }
+    toProviderCycle(cycle, nodes) {
+        return {
+            ...cycle,
+            path: cycle.path.map((key) => this.toProviderCyclePathItem(key, nodes)),
+        };
+    }
+    toProviderCyclePathItem(key, nodes) {
+        const node = nodes.get(key);
+        if (node) {
+            return {
+                module: { name: node.moduleName },
+                provider: { name: node.name },
+            };
+        }
+        const separatorIndex = key.indexOf(':');
+        if (separatorIndex === -1) {
+            return {
+                module: { name: '' },
+                provider: { name: key },
+            };
+        }
+        return {
+            module: { name: key.slice(0, separatorIndex) },
+            provider: { name: key.slice(separatorIndex + 1) },
         };
     }
+    getCycleType(source, target, graph) {
+        if (source === target || graph.get(target)?.has(source)) {
+            return 'direct';
+        }
+        return 'indirect';
+    }
+    findPath(source, target, graph) {
+        const visited = new Set();
+        const pendingPaths = [[source]];
+        while (pendingPaths.length > 0) {
+            const currentPath = pendingPaths.shift();
+            const current = currentPath?.[currentPath.length - 1];
+            if (!currentPath || !current || visited.has(current)) {
+                continue;
+            }
+            if (current === target) {
+                return currentPath;
+            }
+            visited.add(current);
+            for (const next of graph.get(current) ?? []) {
+                pendingPaths.push([...currentPath, next]);
+            }
+        }
+        return [source, target];
+    }
+    findReachableKeys(source, graph) {
+        const reachableKeys = new Set();
+        const pendingKeys = [...(graph.get(source) ?? [])];
+        while (pendingKeys.length > 0) {
+            const currentKey = pendingKeys.pop();
+            if (!currentKey || reachableKeys.has(currentKey)) {
+                continue;
+            }
+            reachableKeys.add(currentKey);
+            for (const nextKey of graph.get(currentKey) ?? []) {
+                pendingKeys.push(nextKey);
+            }
+        }
+        return reachableKeys;
+    }
+    dependencyNodeKey(moduleName, dependencyName) {
+        return `${moduleName}:${dependencyName}`;
+    }
     enrichDependency(dependency, currentModule) {
         const colonIndex = dependency.indexOf(':');
         if (colonIndex !== -1) {