dependency-cruiser 17.3.4 → 17.3.5-beta-2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dependency-cruiser",
-	"version": "17.3.4",
+	"version": "17.3.5-beta-2",
 	"description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
 	"keywords": [
 		"static analysis",

package/src/cache/metadata-strategy.mjs

@@ -21,6 +21,7 @@ export default class MetaDataStrategy {
 	/**
 	 * @param {string} _pDirectory
 	 * @param {ICruiseResult} _pCachedCruiseResult
+	 * @param {IStrictCruiseOptions} pCruiseOptions
 	 * @param {Object} pOptions
 	 * @param {Set<string>} pOptions.extensions
 	 * @param {Set<changeType>=} pOptions.interestingChangeTypes

package/src/enrich/derive/circular.mjs

@@ -1,4 +1,5 @@
 /* eslint-disable security/detect-object-injection */
+import IndexedModuleGraph from "#graph-utl/indexed-module-graph.mjs";
 
 /** @import { IFlattenedRuleSet } from "../../../types/rule-set.mjs" */
 
@@ -44,29 +45,33 @@ function addCircularityCheckToDependency(
 }
 
 /**
- * Runs through all dependencies of all pNodes, for each of them determines
+ * Runs through all dependencies of all pModulesOrFolders, for each of them determines
  * whether it's (part of a) circular (relationship) and returns the
  * dependencies with that added.
  */
 export default function detectAndAddCycles(
-	pNodes,
-	pIndexedNodes,
+	pModulesOrFolders,
 	{ pSourceAttribute, pDependencyName, pSkipAnalysisNotInRules, pRuleSet },
 ) {
 	if (!pSkipAnalysisNotInRules || hasCycleRule(pRuleSet)) {
-		return pNodes.map((pModule) => ({
-			...pModule,
-			dependencies: pModule.dependencies.map((pToDep) =>
+		const lIndexedGraph = new IndexedModuleGraph(
+			pModulesOrFolders,
+			pSourceAttribute,
+		);
+
+		return pModulesOrFolders.map((pModuleOrFolder) => ({
+			...pModuleOrFolder,
+			dependencies: pModuleOrFolder.dependencies.map((pToDep) =>
 				addCircularityCheckToDependency(
-					pIndexedNodes,
-					pModule[pSourceAttribute],
+					lIndexedGraph,
+					pModuleOrFolder[pSourceAttribute],
 					pToDep,
 					pDependencyName,
 				),
 			),
 		}));
 	}
-	return pNodes.map((pModule) => ({
+	return pModulesOrFolders.map((pModule) => ({
 		...pModule,
 		dependencies: pModule.dependencies.map((pToDep) => ({
 			...pToDep,

package/src/enrich/derive/dependents.mjs

@@ -1,13 +1,14 @@
-import { isDependent } from "./module-utl.mjs";
-
 /** @import { IFlattenedRuleSet } from "../../../types/rule-set.mjs" */
 
+import ModuleGraphWithDependencySet from "#graph-utl/module-graph-with-dependency-set.mjs";
+
 function isDependentsRule(pRule) {
 	// used in folder rules and when moreUnstable is in the 'to' => governed by
-	// the 'metrics' flag in options, sot not going to repeat that here
+	// the 'metrics' flag in options, so not going to repeat that here
 
-	// dependents are used in the orphans analsys. However, there is a fall back
-	// where it does its own analysis, so not going to repeat that check here.
+	// dependents are used in the orphans analysis. However, there is a fall back
+	// where it does its own analysis which is faster on itself, so not going
+	// to repeat that check here either.
 	return (
 		/* c8 ignore start */
 		Object.hasOwn(pRule?.module ?? {}, "numberOfDependentsLessThan") ||
@@ -16,13 +17,6 @@ function isDependentsRule(pRule) {
 	);
 }
 
-export function getDependents(pModule, pModules) {
-	// perf between O(n) in an unconnected graph and O(n^2) in a fully connected one
-	return pModules
-		.filter(isDependent(pModule.source))
-		.map((pDependentModule) => pDependentModule.source);
-}
-
 /**
  * @param {IFlattenedRuleSet} pRuleSet
  * @returns {boolean}
@@ -39,9 +33,17 @@ export default function addDependents(
 	{ skipAnalysisNotInRules, metrics, ruleSet },
 ) {
 	if (!skipAnalysisNotInRules || metrics || hasDependentsRule(ruleSet)) {
+		// creating this optimized structure here might seem overkill, but on
+		// large graphs it pays off significantly - creation is a few centiseconds
+		// but it cuts analysis in half on large graphs (and even on smaller
+		// graphs it's a win, even though just a few milliseconds)
+		const lModulesWithDependencySet = new ModuleGraphWithDependencySet(
+			pModules,
+		);
+
 		return pModules.map((pModule) => ({
 			...pModule,
-			dependents: getDependents(pModule, pModules),
+			dependents: lModulesWithDependencySet.getDependents(pModule),
 		}));
 	}
 	return pModules;

package/src/enrich/derive/folders/aggregate-to-folders.mjs

@@ -9,7 +9,6 @@ import {
 	getParentFolders,
 	object2Array,
 } from "./utl.mjs";
-import IndexedModuleGraph from "#graph-utl/indexed-module-graph.mjs";
 import { uniq } from "#utl/array-util.mjs";
 
 function upsertCouplings(pAllDependents, pNewDependents) {
@@ -148,7 +147,7 @@ export default function aggregateToFolders(pModules, pOptions = {}) {
 		.map(deNormalizeInstability);
 	lFolders = lFolders.concat(getSinks(lFolders));
 
-	return detectCycles(lFolders, new IndexedModuleGraph(lFolders, "name"), {
+	return detectCycles(lFolders, {
 		pSourceAttribute: "name",
 		pDependencyName: "name",
 		pSkipAnalysisNotInRules: pOptions.skipAnalysisNotInRules,

package/src/enrich/derive/metrics/get-module-metrics.mjs

@@ -1,5 +1,4 @@
 import { calculateInstability, metricsAreCalculable } from "../module-utl.mjs";
-import IndexedModuleGraph from "#graph-utl/indexed-module-graph.mjs";
 
 export function addInstabilityMetric(pModule) {
 	return {
@@ -15,25 +14,23 @@ export function addInstabilityMetric(pModule) {
 	};
 }
 
-function addInstabilityToDependency(pAllModules) {
-	const lIndexedModules = new IndexedModuleGraph(pAllModules);
+function addInstabilityToDependency(pIndexedModules) {
 	return (pDependency) => ({
 		...pDependency,
 		instability:
-			(lIndexedModules.findVertexByName(pDependency.resolved) || {})
+			(pIndexedModules.findVertexByName(pDependency.resolved) || {})
 				.instability || 0,
 	});
 }
 
 export function deNormalizeInstabilityMetricsToDependencies(
 	pModule,
-	_,
-	pAllModules,
+	pIndexedModules,
 ) {
 	return {
 		...pModule,
 		dependencies: pModule.dependencies.map(
-			addInstabilityToDependency(pAllModules),
+			addInstabilityToDependency(pIndexedModules),
 		),
 	};
 }

package/src/enrich/derive/metrics/index.mjs

@@ -2,12 +2,16 @@ import {
 	addInstabilityMetric,
 	deNormalizeInstabilityMetricsToDependencies,
 } from "./get-module-metrics.mjs";
+import IndexedModuleGraph from "#graph-utl/indexed-module-graph.mjs";
 
 export default function deriveModulesMetrics(pModules, pOptions) {
 	if (pOptions.metrics) {
-		return pModules
-			.map(addInstabilityMetric)
-			.map(deNormalizeInstabilityMetricsToDependencies);
+		const lModules = pModules.map(addInstabilityMetric);
+		const lIndexedModules = new IndexedModuleGraph(lModules);
+
+		return lModules.map((pModule) =>
+			deNormalizeInstabilityMetricsToDependencies(pModule, lIndexedModules),
+		);
 	}
 	return pModules;
 }

package/src/enrich/derive/module-utl.mjs

@@ -1,10 +1,3 @@
-export function isDependent(pResolvedName) {
-	return (pModule) =>
-		pModule.dependencies.some(
-			(pDependency) => pDependency.resolved === pResolvedName,
-		);
-}
-
 export function metricsAreCalculable(pModule) {
 	return (
 		!pModule.coreModule &&

package/src/enrich/derive/orphan/index.mjs

@@ -1,4 +1,5 @@
 import isOrphan from "./is-orphan.mjs";
+import ModuleGraphWithDependencySet from "#graph-utl/module-graph-with-dependency-set.mjs";
 
 /** @import { IFlattenedRuleSet } from "../../../../types/rule-set.mjs" */
 
@@ -25,9 +26,19 @@ export default function deriveOrphans(
 	{ skipAnalysisNotInRules, ruleSet },
 ) {
 	if (!skipAnalysisNotInRules || hasOrphanRule(ruleSet)) {
+		// just like the dependents derivation, creating this data structure
+		// might seem overkill, but it can save effort here as well, even though
+		// isOrphan has early exits the dependents derivation doesn't:
+		// - when the module already has dependencies (quick length check)
+		// - when dependents are already calculated (quick length check as well). If
+		//   they are, the lModulesWithDependencySet is created for naught.
+		const lModulesWithDependencySet = new ModuleGraphWithDependencySet(
+			pModules,
+		);
+
 		return pModules.map((pModule) => ({
 			...pModule,
-			orphan: isOrphan(pModule, pModules),
+			orphan: isOrphan(pModule, lModulesWithDependencySet),
 		}));
 	}
 	return pModules;

package/src/enrich/derive/orphan/is-orphan.mjs

@@ -1,6 +1,11 @@
-import { isDependent } from "../module-utl.mjs";
-
-export default function isOrphan(pModule, pGraph) {
+/**
+ * returns true if the given module has no dependencies and no dependents
+ *
+ * @param {import("../../../../types/dependency-cruiser.mjs").IModule} pModule
+ * @param {import("#graph-utl/module-graph-with-dependency-set.mjs").default} pModulesWithDependencySet
+ * @returns {boolean}
+ */
+export default function isOrphan(pModule, pModulesWithDependencySet) {
 	if (pModule.dependencies.length > 0) {
 		return false;
 	}
@@ -10,5 +15,5 @@ export default function isOrphan(pModule, pGraph) {
 		return pModule.dependents.length === 0;
 	}
 	// ... otherwise calculate them
-	return !pGraph.some(isDependent(pModule.source));
+	return !pModulesWithDependencySet.moduleHasDependents(pModule);
 }

package/src/enrich/enrich-modules.mjs

@@ -5,7 +5,6 @@ import deriveReachable from "./derive/reachable.mjs";
 import addValidations from "./add-validations.mjs";
 import softenKnownViolations from "./soften-known-violations.mjs";
 import deriveModuleMetrics from "./derive/metrics/index.mjs";
-import IndexedModuleGraph from "#graph-utl/indexed-module-graph.mjs";
 import addFocus from "#graph-utl/add-focus.mjs";
 import { bus } from "#utl/bus.mjs";
 
@@ -18,8 +17,8 @@ import { bus } from "#utl/bus.mjs";
  */
 export default function enrichModules(pModules, pOptions) {
 	bus.info("analyze: cycles");
-	const lIndexedModules = new IndexedModuleGraph(pModules);
-	let lModules = deriveCycles(pModules, lIndexedModules, {
+
+	let lModules = deriveCycles(pModules, {
 		pSourceAttribute: "source",
 		pDependencyName: "resolved",
 		pSkipAnalysisNotInRules: pOptions.skipAnalysisNotInRules,

package/src/graph-utl/module-graph-with-dependency-set.mjs

@@ -0,0 +1,41 @@
+export default class ModuleGraphWithDependencySet {
+	/** @type {Array<{source: string, dependencies: Set<string>}>} */
+	#modulesWithDependencySet;
+	/**
+	 * Creates a module graph optimized for querying dependents
+	 * @constructor
+	 * @param {import("../../types/dependency-cruiser.mjs").IModule[]} pModules
+	 */
+	constructor(pModules) {
+		this.#modulesWithDependencySet = pModules.map((pModule) => ({
+			source: pModule.source,
+			dependencies: new Set(
+				pModule.dependencies.map((pDependency) => pDependency.resolved),
+			),
+		}));
+	}
+
+	/**
+	 * Returns true if the given module has dependents in the graph, false otherwise
+	 *
+	 * @param {import("../../types/dependency-cruiser.mjs").IModule} pModule
+	 * @returns {boolean}
+	 */
+	moduleHasDependents(pModule) {
+		return this.#modulesWithDependencySet.some(({ dependencies }) =>
+			dependencies.has(pModule.source),
+		);
+	}
+
+	/**
+	 * Returns an array of module source paths that depend on the given module
+	 *
+	 * @param {import("../../types/dependency-cruiser.mjs").IModule} pModule
+	 * @returns {Array<string>}
+	 */
+	getDependents(pModule) {
+		return this.#modulesWithDependencySet
+			.filter(({ dependencies }) => dependencies.has(pModule.source))
+			.map(({ source }) => source);
+	}
+}

package/src/meta.cjs

@@ -1,6 +1,6 @@
 /* generated - don't edit */
 module.exports = {
-	version: "17.3.4",
+	version: "17.3.5-beta-2",
 	engines: {
 		node: "^20.12||^22||>=24",
 	},