@nexus-ioc/graph-analyzer 0.1.0

package/dist/analyzer/circular-dependency-detector.d.ts

@@ -0,0 +1,94 @@
+import type { ParseEntryFile } from "../parser/parse-entry-file";
+import type { ParseNsModule } from "../parser/parse-ns-module";
+/**
+ * Represents a circular dependency cycle
+ */
+export interface CircularDependency {
+    /** Type of circular dependency */
+    type: "module" | "provider";
+    /** Path of nodes forming the cycle (e.g., ["A", "B", "C", "A"]) */
+    cycle: string[];
+    /** Severity level */
+    severity: "error" | "warning";
+    /** Human-readable description */
+    message: string;
+}
+/**
+ * Result of circular dependency analysis
+ */
+export interface CircularDependencyAnalysis {
+    /** Whether any circular dependencies were found */
+    hasCircularDependencies: boolean;
+    /** List of all detected circular dependencies */
+    circularDependencies: CircularDependency[];
+    /** Count of module-level cycles */
+    moduleCircularCount: number;
+    /** Count of provider-level cycles */
+    providerCircularCount: number;
+}
+/**
+ * Detects circular dependencies in module imports and provider dependencies
+ *
+ * Uses depth-first search (DFS) to detect cycles in the dependency graph.
+ * Can detect both module-level circular imports and provider-level circular dependencies.
+ *
+ * @example
+ * ```typescript
+ * const detector = new CircularDependencyDetector(modulesGraph);
+ * const analysis = detector.analyze();
+ *
+ * if (analysis.hasCircularDependencies) {
+ *   console.error(`Found ${analysis.circularDependencies.length} circular dependencies`);
+ *   analysis.circularDependencies.forEach(cycle => {
+ *     console.error(`${cycle.type}: ${cycle.cycle.join(' -> ')}`);
+ *   });
+ * }
+ * ```
+ */
+export declare class CircularDependencyDetector {
+    private readonly graph;
+    /**
+     * Create a new CircularDependencyDetector instance
+     *
+     * @param graph - Map of module names to parsed modules
+     */
+    constructor(graph: Map<string, ParseNsModule | ParseEntryFile>);
+    /**
+     * Analyze the dependency graph for circular dependencies
+     *
+     * Performs both module-level and provider-level circular dependency detection.
+     *
+     * @returns CircularDependencyAnalysis with all detected cycles
+     */
+    analyze(): CircularDependencyAnalysis;
+    /**
+     * Detect circular dependencies in module imports
+     *
+     * Uses DFS to find cycles in the module import graph.
+     * A cycle exists when a module imports another module that eventually imports back to the original.
+     *
+     * @returns Array of detected module circular dependencies
+     */
+    private detectModuleCircularDependencies;
+    /**
+     * Depth-first search for module circular dependencies
+     */
+    private dfsModules;
+    /**
+     * Detect circular dependencies in provider dependencies
+     *
+     * Uses DFS to find cycles in the provider dependency graph.
+     * A cycle exists when a provider depends on another provider that eventually depends back on the original.
+     *
+     * @returns Array of detected provider circular dependencies
+     */
+    private detectProviderCircularDependencies;
+    /**
+     * Build a map of provider tokens to their dependencies
+     */
+    private buildProviderDependencyMap;
+    /**
+     * Depth-first search for provider circular dependencies
+     */
+    private dfsProviders;
+}

package/dist/analyzer/circular-dependency-detector.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircularDependencyDetector = void 0;
+/**
+ * Detects circular dependencies in module imports and provider dependencies
+ *
+ * Uses depth-first search (DFS) to detect cycles in the dependency graph.
+ * Can detect both module-level circular imports and provider-level circular dependencies.
+ *
+ * @example
+ * ```typescript
+ * const detector = new CircularDependencyDetector(modulesGraph);
+ * const analysis = detector.analyze();
+ *
+ * if (analysis.hasCircularDependencies) {
+ *   console.error(`Found ${analysis.circularDependencies.length} circular dependencies`);
+ *   analysis.circularDependencies.forEach(cycle => {
+ *     console.error(`${cycle.type}: ${cycle.cycle.join(' -> ')}`);
+ *   });
+ * }
+ * ```
+ */
+class CircularDependencyDetector {
+    /**
+     * Create a new CircularDependencyDetector instance
+     *
+     * @param graph - Map of module names to parsed modules
+     */
+    constructor(graph) {
+        this.graph = graph;
+    }
+    /**
+     * Analyze the dependency graph for circular dependencies
+     *
+     * Performs both module-level and provider-level circular dependency detection.
+     *
+     * @returns CircularDependencyAnalysis with all detected cycles
+     */
+    analyze() {
+        const circularDependencies = [];
+        // Detect module-level circular imports
+        const moduleCycles = this.detectModuleCircularDependencies();
+        circularDependencies.push(...moduleCycles);
+        // Detect provider-level circular dependencies
+        const providerCycles = this.detectProviderCircularDependencies();
+        circularDependencies.push(...providerCycles);
+        return {
+            hasCircularDependencies: circularDependencies.length > 0,
+            circularDependencies,
+            moduleCircularCount: moduleCycles.length,
+            providerCircularCount: providerCycles.length,
+        };
+    }
+    /**
+     * Detect circular dependencies in module imports
+     *
+     * Uses DFS to find cycles in the module import graph.
+     * A cycle exists when a module imports another module that eventually imports back to the original.
+     *
+     * @returns Array of detected module circular dependencies
+     */
+    detectModuleCircularDependencies() {
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const path = [];
+        const entryModule = this.graph.get("entry");
+        if (!entryModule || !entryModule.name) {
+            return cycles;
+        }
+        // Start DFS from entry module
+        this.dfsModules(entryModule.name, visited, recursionStack, path, cycles);
+        return cycles;
+    }
+    /**
+     * Depth-first search for module circular dependencies
+     */
+    dfsModules(moduleName, visited, recursionStack, path, cycles) {
+        // Mark current node as visited and add to recursion stack
+        visited.add(moduleName);
+        recursionStack.add(moduleName);
+        path.push(moduleName);
+        const parseNsModule = this.graph.get(moduleName);
+        if (!parseNsModule) {
+            // Clean up and return
+            recursionStack.delete(moduleName);
+            path.pop();
+            return;
+        }
+        // Visit all imported modules
+        for (const importedModule of parseNsModule.imports) {
+            if (!visited.has(importedModule)) {
+                // Recursively visit unvisited module
+                this.dfsModules(importedModule, visited, recursionStack, path, cycles);
+            }
+            else if (recursionStack.has(importedModule)) {
+                // Found a cycle - extract the cycle path
+                const cycleStartIndex = path.indexOf(importedModule);
+                const cyclePath = path.slice(cycleStartIndex);
+                cyclePath.push(importedModule); // Complete the cycle
+                cycles.push({
+                    type: "module",
+                    cycle: cyclePath,
+                    severity: "error",
+                    message: `Circular module import detected: ${cyclePath.join(" -> ")}`,
+                });
+            }
+        }
+        // Remove from recursion stack and path
+        recursionStack.delete(moduleName);
+        path.pop();
+    }
+    /**
+     * Detect circular dependencies in provider dependencies
+     *
+     * Uses DFS to find cycles in the provider dependency graph.
+     * A cycle exists when a provider depends on another provider that eventually depends back on the original.
+     *
+     * @returns Array of detected provider circular dependencies
+     */
+    detectProviderCircularDependencies() {
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const path = [];
+        // Build provider dependency map
+        const providerDeps = this.buildProviderDependencyMap();
+        // Run DFS from each provider
+        for (const providerToken of providerDeps.keys()) {
+            if (!visited.has(providerToken)) {
+                this.dfsProviders(providerToken, providerDeps, visited, recursionStack, path, cycles);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Build a map of provider tokens to their dependencies
+     */
+    buildProviderDependencyMap() {
+        const providerDeps = new Map();
+        // Traverse all modules
+        for (const [key, value] of this.graph.entries()) {
+            if (key === "entry")
+                continue;
+            const parseNsModule = value;
+            if (!parseNsModule.providers)
+                continue;
+            // Extract dependencies for each provider
+            for (const provider of parseNsModule.providers) {
+                if (!provider.token)
+                    continue;
+                const dependencies = [];
+                if (provider.dependencies && Array.isArray(provider.dependencies)) {
+                    for (const dep of provider.dependencies) {
+                        if (dep.token && !dep.optional) {
+                            dependencies.push(dep.token);
+                        }
+                    }
+                }
+                providerDeps.set(provider.token, dependencies);
+            }
+        }
+        return providerDeps;
+    }
+    /**
+     * Depth-first search for provider circular dependencies
+     */
+    dfsProviders(providerToken, providerDeps, visited, recursionStack, path, cycles) {
+        // Mark current node as visited and add to recursion stack
+        visited.add(providerToken);
+        recursionStack.add(providerToken);
+        path.push(providerToken);
+        const dependencies = providerDeps.get(providerToken) || [];
+        // Visit all dependencies
+        for (const depToken of dependencies) {
+            if (!providerDeps.has(depToken)) {
+                // Dependency is not a provider (might be external), skip
+                continue;
+            }
+            if (!visited.has(depToken)) {
+                // Recursively visit unvisited dependency
+                this.dfsProviders(depToken, providerDeps, visited, recursionStack, path, cycles);
+            }
+            else if (recursionStack.has(depToken)) {
+                // Found a cycle - extract the cycle path
+                const cycleStartIndex = path.indexOf(depToken);
+                const cyclePath = path.slice(cycleStartIndex);
+                cyclePath.push(depToken); // Complete the cycle
+                cycles.push({
+                    type: "provider",
+                    cycle: cyclePath,
+                    severity: "error",
+                    message: `Circular provider dependency detected: ${cyclePath.join(" -> ")}`,
+                });
+            }
+        }
+        // Remove from recursion stack and path
+        recursionStack.delete(providerToken);
+        path.pop();
+    }
+}
+exports.CircularDependencyDetector = CircularDependencyDetector;
+//# sourceMappingURL=circular-dependency-detector.js.map

package/dist/analyzer/circular-dependency-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circular-dependency-detector.js","sourceRoot":"","sources":["../../src/analyzer/circular-dependency-detector.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/module-depth-analyzer.d.ts

@@ -0,0 +1,117 @@
+import type { ParseEntryFile } from "../parser/parse-entry-file";
+import type { ParseNsModule } from "../parser/parse-ns-module";
+/**
+ * Information about a module's position in the hierarchy
+ */
+export interface ModuleDepthInfo {
+    /** Module name */
+    name: string;
+    /** Depth level in the import hierarchy (0 = entry module) */
+    depth: number;
+    /** Number of direct imports */
+    directImports: number;
+    /** Number of transitive dependencies (all modules this depends on) */
+    transitiveDependencies: number;
+    /** Number of modules that directly import this module (fan-in) */
+    fanIn: number;
+    /** Number of modules this module directly imports (fan-out) */
+    fanOut: number;
+}
+/**
+ * Depth level information
+ */
+export interface DepthLevel {
+    /** Depth level number */
+    level: number;
+    /** Modules at this depth level */
+    modules: string[];
+    /** Number of modules at this level */
+    count: number;
+}
+/**
+ * Result of module depth analysis
+ */
+export interface ModuleDepthAnalysis {
+    /** Whether depth analysis was performed */
+    hasDepthAnalysis: boolean;
+    /** Maximum depth in the module hierarchy */
+    maxDepth: number;
+    /** Average depth across all modules */
+    averageDepth: number;
+    /** Total number of modules analyzed */
+    totalModules: number;
+    /** Modules at each depth level */
+    depthLevels: DepthLevel[];
+    /** Detailed information for each module */
+    moduleDetails: ModuleDepthInfo[];
+    /** Modules with excessive depth (potential code smell) */
+    deepModules: ModuleDepthInfo[];
+    /** Threshold used for identifying deep modules */
+    deepModuleThreshold: number;
+}
+/**
+ * Analyzes module hierarchy depth and complexity metrics
+ *
+ * Calculates various metrics about module organization including:
+ * - Depth of module import chains
+ * - Module complexity metrics (fan-in, fan-out)
+ * - Identification of overly deep hierarchies
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new ModuleDepthAnalyzer(modulesGraph);
+ * const analysis = analyzer.analyze();
+ *
+ * console.log(`Max depth: ${analysis.maxDepth}`);
+ * console.log(`Average depth: ${analysis.averageDepth.toFixed(2)}`);
+ *
+ * if (analysis.deepModules.length > 0) {
+ *   console.warn(`Found ${analysis.deepModules.length} modules with excessive depth`);
+ * }
+ * ```
+ */
+export declare class ModuleDepthAnalyzer {
+    private readonly graph;
+    private readonly deepModuleThreshold;
+    /**
+     * Create a new ModuleDepthAnalyzer instance
+     *
+     * @param graph - Map of module names to parsed modules
+     * @param deepModuleThreshold - Custom threshold for deep modules (optional)
+     */
+    constructor(graph: Map<string, ParseNsModule | ParseEntryFile>, deepModuleThreshold?: number);
+    /**
+     * Analyze the module hierarchy depth and complexity
+     *
+     * @returns ModuleDepthAnalysis with all calculated metrics
+     */
+    analyze(): ModuleDepthAnalysis;
+    /**
+     * Get all modules from the graph (excluding entry file)
+     */
+    private getModules;
+    /**
+     * Calculate depth for each module using BFS from entry point
+     */
+    private calculateModuleDepths;
+    /**
+     * Calculate complexity metrics for each module
+     */
+    private calculateComplexityMetrics;
+    /**
+     * Calculate fan-in for all modules (how many modules depend on each module)
+     */
+    private calculateFanIn;
+    /**
+     * Calculate transitive dependencies for a module (all modules it depends on)
+     */
+    private calculateTransitiveDependencies;
+    /**
+     * Group modules by depth level
+     */
+    private groupByDepthLevel;
+    /**
+     * Create an empty analysis result
+     */
+    private createEmptyAnalysis;
+}

package/dist/analyzer/module-depth-analyzer.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleDepthAnalyzer = void 0;
+/**
+ * Analyzes module hierarchy depth and complexity metrics
+ *
+ * Calculates various metrics about module organization including:
+ * - Depth of module import chains
+ * - Module complexity metrics (fan-in, fan-out)
+ * - Identification of overly deep hierarchies
+ *
+ * @example
+ * ```typescript
+ * const analyzer = new ModuleDepthAnalyzer(modulesGraph);
+ * const analysis = analyzer.analyze();
+ *
+ * console.log(`Max depth: ${analysis.maxDepth}`);
+ * console.log(`Average depth: ${analysis.averageDepth.toFixed(2)}`);
+ *
+ * if (analysis.deepModules.length > 0) {
+ *   console.warn(`Found ${analysis.deepModules.length} modules with excessive depth`);
+ * }
+ * ```
+ */
+class ModuleDepthAnalyzer {
+    /**
+     * Create a new ModuleDepthAnalyzer instance
+     *
+     * @param graph - Map of module names to parsed modules
+     * @param deepModuleThreshold - Custom threshold for deep modules (optional)
+     */
+    constructor(graph, deepModuleThreshold = 5) {
+        this.graph = graph;
+        this.deepModuleThreshold = deepModuleThreshold;
+    }
+    /**
+     * Analyze the module hierarchy depth and complexity
+     *
+     * @returns ModuleDepthAnalysis with all calculated metrics
+     */
+    analyze() {
+        const modules = this.getModules();
+        if (modules.length === 0) {
+            return this.createEmptyAnalysis();
+        }
+        // Calculate depth for each module
+        const moduleDepths = this.calculateModuleDepths();
+        // Calculate complexity metrics
+        const moduleDetails = this.calculateComplexityMetrics(moduleDepths);
+        // Group modules by depth level
+        const depthLevels = this.groupByDepthLevel(moduleDetails);
+        // Calculate statistics
+        const maxDepth = Math.max(...moduleDetails.map((m) => m.depth));
+        const averageDepth = moduleDetails.reduce((sum, m) => sum + m.depth, 0) / moduleDetails.length;
+        // Identify deep modules
+        const deepModules = moduleDetails.filter((m) => m.depth >= this.deepModuleThreshold);
+        return {
+            hasDepthAnalysis: true,
+            maxDepth,
+            averageDepth,
+            totalModules: moduleDetails.length,
+            depthLevels,
+            moduleDetails,
+            deepModules,
+            deepModuleThreshold: this.deepModuleThreshold,
+        };
+    }
+    /**
+     * Get all modules from the graph (excluding entry file)
+     */
+    getModules() {
+        const modules = [];
+        for (const [key, value] of this.graph.entries()) {
+            if (key !== "entry" && "imports" in value) {
+                modules.push(value);
+            }
+        }
+        return modules;
+    }
+    /**
+     * Calculate depth for each module using BFS from entry point
+     */
+    calculateModuleDepths() {
+        const depths = new Map();
+        const entry = this.graph.get("entry");
+        if (!entry || !entry.name) {
+            return depths;
+        }
+        // Start BFS from entry module
+        const queue = [
+            { name: entry.name, depth: 0 },
+        ];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (visited.has(current.name)) {
+                continue;
+            }
+            visited.add(current.name);
+            depths.set(current.name, current.depth);
+            // Get module from graph
+            const module = this.graph.get(current.name);
+            if (!module || !("imports" in module)) {
+                continue;
+            }
+            // Add all imports to queue with incremented depth
+            for (const importName of module.imports) {
+                if (!visited.has(importName)) {
+                    queue.push({ name: importName, depth: current.depth + 1 });
+                }
+            }
+        }
+        return depths;
+    }
+    /**
+     * Calculate complexity metrics for each module
+     */
+    calculateComplexityMetrics(moduleDepths) {
+        const moduleDetails = [];
+        const fanInMap = this.calculateFanIn();
+        for (const [moduleName, depth] of moduleDepths.entries()) {
+            const module = this.graph.get(moduleName);
+            if (!module || !("imports" in module)) {
+                continue;
+            }
+            const directImports = module.imports.length;
+            const transitiveDependencies = this.calculateTransitiveDependencies(moduleName);
+            const fanIn = fanInMap.get(moduleName) || 0;
+            const fanOut = directImports;
+            moduleDetails.push({
+                name: moduleName,
+                depth,
+                directImports,
+                transitiveDependencies,
+                fanIn,
+                fanOut,
+            });
+        }
+        return moduleDetails;
+    }
+    /**
+     * Calculate fan-in for all modules (how many modules depend on each module)
+     */
+    calculateFanIn() {
+        const fanInMap = new Map();
+        for (const [key, value] of this.graph.entries()) {
+            if (key === "entry" || !("imports" in value)) {
+                continue;
+            }
+            const module = value;
+            for (const importName of module.imports) {
+                fanInMap.set(importName, (fanInMap.get(importName) || 0) + 1);
+            }
+        }
+        return fanInMap;
+    }
+    /**
+     * Calculate transitive dependencies for a module (all modules it depends on)
+     */
+    calculateTransitiveDependencies(moduleName) {
+        const visited = new Set();
+        const queue = [moduleName];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (visited.has(current)) {
+                continue;
+            }
+            visited.add(current);
+            const module = this.graph.get(current);
+            if (!module || !("imports" in module)) {
+                continue;
+            }
+            for (const importName of module.imports) {
+                if (!visited.has(importName)) {
+                    queue.push(importName);
+                }
+            }
+        }
+        // Subtract 1 to exclude the module itself
+        return visited.size - 1;
+    }
+    /**
+     * Group modules by depth level
+     */
+    groupByDepthLevel(moduleDetails) {
+        const levelMap = new Map();
+        for (const module of moduleDetails) {
+            const modules = levelMap.get(module.depth) || [];
+            modules.push(module.name);
+            levelMap.set(module.depth, modules);
+        }
+        const depthLevels = [];
+        for (const [level, modules] of levelMap.entries()) {
+            depthLevels.push({
+                level,
+                modules,
+                count: modules.length,
+            });
+        }
+        // Sort by level
+        depthLevels.sort((a, b) => a.level - b.level);
+        return depthLevels;
+    }
+    /**
+     * Create an empty analysis result
+     */
+    createEmptyAnalysis() {
+        return {
+            hasDepthAnalysis: false,
+            maxDepth: 0,
+            averageDepth: 0,
+            totalModules: 0,
+            depthLevels: [],
+            moduleDetails: [],
+            deepModules: [],
+            deepModuleThreshold: this.deepModuleThreshold,
+        };
+    }
+}
+exports.ModuleDepthAnalyzer = ModuleDepthAnalyzer;
+//# sourceMappingURL=module-depth-analyzer.js.map

package/dist/analyzer/module-depth-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-depth-analyzer.js","sourceRoot":"","sources":["../../src/analyzer/module-depth-analyzer.ts"],"names":[],"mappings":"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"}