dependency-cruiser 18.0.0 → 18.1.1

package/src/utl/array-util.mjs

@@ -4,7 +4,7 @@
  *
  * @param {string[]} pLeftArray an array of strings
  * @param {string[]} pRightArray another array of strings
- * @return {boolean} true if there's at least one element in pLeftArray also in pRightArray
+ * @returns {boolean} true if there's at least one element in pLeftArray also in pRightArray
  */
 export function intersects(pLeftArray, pRightArray) {
 	if (pLeftArray.length === 0 || pRightArray.length === 0) {

package/src/utl/find-all-files.mjs

@@ -56,7 +56,7 @@ function walk(
 function readIgnoreFile(pFileName) {
 	try {
 		return readFileSync(pFileName, "utf8");
-	} catch (pError) {
+	} catch {
 		return "";
 	}
 }

package/src/utl/get-extension.mjs

@@ -13,7 +13,7 @@ const EXTENSION_RE = /(?<extension>(?:(?:\.d\.(?:[cm])?ts)|\.coffee\.md)$)/;
  * .ts, .cts and .mts
  *
  * @param {string} pFileName path to the file to be parsed
- * @return {string}          extension
+ * @returns {string}          extension
  */
 export default function getExtension(pFileName) {
 	const lMatchResult = EXTENSION_RE.exec(pFileName);

package/src/utl/path-to-posix.mjs

@@ -17,7 +17,7 @@ import path from "node:path";
  * @param  {string} pFilePath   the path to transform
  * @param  {path} pPathModule? optional - the path module/ object to use (for testing
  *                              this module on posix platforms only; defaults to require('path'))
- * @return {string}             the transformed path
+ * @returns {string}             the transformed path
  */
 export default function pathToPosix(pFilePath, pPathModule = path) {
 	const lPathModule = pPathModule || path;

package/src/utl/regex-util.mjs

@@ -29,7 +29,7 @@ export function clearRegExpCache() {
  * This fills our current need. Later we can expand it to return all group
  * matches.
  *
- * @param {import("../../types/restrictions").IFromRestriction} pFromRestriction
+ * @param {import("../../types/restrictions.mjs").IFromRestriction} pFromRestriction
  * @param {string} pActualPath
  * @returns {string[]|null}
  */
@@ -41,7 +41,9 @@ export function extractGroups(pFromRestriction, pActualPath) {
 		// except before it enters here it has already been 'normalized' to a string
 		// so it can be safely passed to match. The right solution here (TODO)
 		// is to create a separate type for NormalizedFromRestriction
-		let lMatchResult = getCachedRegExp(pFromRestriction.path).exec(pActualPath);
+		const lMatchResult = getCachedRegExp(pFromRestriction.path).exec(
+			pActualPath,
+		);
 
 		if (lMatchResult && lMatchResult.length > 1) {
 			lReturnValue = lMatchResult.filter(

package/src/utl/try-import.mjs

@@ -60,7 +60,7 @@ export default async function tryImport(pModuleName, pSemanticVersion) {
 		}
 		const lModule = await import(pModuleName);
 		return lModule.default ? lModule.default : lModule;
-	} catch (pError) {
+	} catch {
 		return false;
 	}
 }

package/src/utl/try-require.cjs

@@ -6,7 +6,7 @@ const extractRootModuleName = require("./extract-root-module-name.cjs");
 /**
  * @throws {Error}
  * @param pModuleName the name of the module to get the version for
- * @return the version of the module identified by pModuleName
+ * @returns the version of the module identified by pModuleName
  */
 function getVersion(pModuleName) {
 	// @ts-expect-error TS2345 extractRootModuleName can return either a string or
@@ -26,7 +26,7 @@ function getVersion(pModuleName) {
  *
  * @param {string} pModuleName      the name of the module to resolve
  * @param {string} [pSemanticVersion] (optional) a semantic version (range)
- * @return {NodeModule | false }the (resolved) module identified by pModuleName or false
+ * @returns {NodeModule | false }the (resolved) module identified by pModuleName or false
  */
 function tryRequire(pModuleName, pSemanticVersion) {
 	try {
@@ -43,7 +43,7 @@ function tryRequire(pModuleName, pSemanticVersion) {
 		}
 		// eslint-disable-next-line import/no-dynamic-require, n/global-require, security/detect-non-literal-require
 		return require(pModuleName);
-	} catch (pError) {
+	} catch {
 		return false;
 	}
 }

package/src/validate/index.mjs

@@ -18,7 +18,7 @@ function compareSeverity(pFirst, pSecond) {
 }
 
 function validateAgainstAllowedRules(pRuleSet, pMatchModule, pFrom, pTo) {
-	let lFoundRuleViolations = [];
+	const lFoundRuleViolations = [];
 
 	if (pRuleSet.allowed) {
 		const lInterestingAllowedRules = pRuleSet.allowed.filter(
@@ -75,7 +75,7 @@ function validateAgainstRequiredRules(pRuleSet, pModule, pMatchModule) {
  */
 function validateAgainstRules(pRuleSet, pFrom, pTo, pMatchModule) {
 	/** @type {IValidationResult} */
-	let lReturnValue = { valid: true };
+	const lReturnValue = { valid: true };
 
 	const lFoundRuleViolations = validateAgainstAllowedRules(
 		pRuleSet,

package/types/config-utl/extract-babel-config.d.mts

@@ -5,7 +5,7 @@
  * Silently fails if a supported @babel/core version can't be found
  *
  * @param pBabelConfigFileName
- * @return babel config as an object
+ * @returns babel config as an object
  * @throws when the babel config has an unknown extension OR
  *         when the babel config is invalid OR
  *         when dependency-cruiser can't yet process it

package/types/config-utl/extract-depcruise-config.d.mts

@@ -17,7 +17,7 @@ import type { IConfiguration } from "../configuration.mjs";
  * @param pConfigFileName
  * @param pAlreadyVisited
  * @param pBaseDirectory
- * @return dependency-cruiser configuration
+ * @returns dependency-cruiser configuration
  * @throws when the config is not valid (/ does not exist/ isn't readable)
  */
 export default function extractDepcruiseConfig(

package/types/config-utl/extract-depcruise-options.d.mts

@@ -10,7 +10,7 @@ import type { ICruiseOptions } from "../options.mjs";
  * ```
  *
  * @param pConfigFileName
- * @return dependency-cruiser options
+ * @returns dependency-cruiser options
  * @throws when the config is not valid (/ does not exist/ isn't readable)
  */
 export default function extractDepcruiseOptions(

package/types/config-utl/extract-ts-config.d.mts

@@ -7,7 +7,7 @@ import type { ParsedCommandLine } from "typescript";
  * Silently fails if a supported version of the typescript compiler isn't available
  *
  * @param pTSConfigFileName
- * @return tsconfig as an object
+ * @returns tsconfig as an object
  * @throws {Error} when the tsconfig is invalid/ has errors
  * @throws {TypeError} when the tsconfig is unreadable
  */

package/types/config-utl/extract-webpack-resolve-config.d.mts

@@ -8,7 +8,7 @@ import type { ResolveOptions } from "enhanced-resolve";
  * @param pWebpackConfigFilename
  * @param pEnvironment
  * @param pArguments
- * @return webpack resolve config as an object
+ * @returns webpack resolve config as an object
  * @throws when the webpack config isn't usable (e.g. because it
  *         doesn't exist, or because it's invalid)
  */

package/types/cruise-result.d.mts

@@ -6,10 +6,15 @@ import type {
 	ModuleSystemType,
 	ProtocolType,
 	ExperimentalStatsType,
+	SeverityType,
 } from "./shared-types.mjs";
 import type { IViolation } from "./violations.mjs";
 import type { IRuleSummary } from "./rule-summary.mjs";
 import type { IChange } from "watskeburt";
+import type {
+	IAvailableExtension,
+	IAvailableTranspiler,
+} from "./environment.mjs";
 
 export interface IRevisionChange extends IChange {
 	// optional because
@@ -359,6 +364,28 @@ export interface ISummary {
 	 * the number of warnings in the dependencies
 	 */
 	warn: number;
+	/**
+	 * information on the environment the cruise ran on
+	 */
+	environment: {
+		version: string;
+		nodeVersionSupported: string;
+		nodeVersionFound: string;
+		osVersionFound: string;
+		transpilersFound: IAvailableTranspiler[];
+		extensionsFound: IAvailableExtension[];
+		/**
+		 * Issues detected in the environment that might have influenced the cruise
+		 * e.g. a missing (supported) typescript transpiler, while there's a tsconfig
+		 */
+		issues?: IEnvironmentIssue[];
+	};
+}
+
+export interface IEnvironmentIssue {
+	severity: SeverityType;
+	name: string;
+	description: string;
 }
 
 /**

package/types/dependency-cruiser.d.mts

@@ -1,6 +1,10 @@
 import type { ICruiseResult } from "./cruise-result.mjs";
 import type { ICruiseOptions, IFormatOptions } from "./options.mjs";
 import type { IResolveOptions } from "./resolve-options.mjs";
+import type {
+	IAvailableExtension,
+	IAvailableTranspiler,
+} from "./environment.mjs";
 
 export type * from "./rule-set.mjs";
 export type * from "./options.mjs";
@@ -8,6 +12,7 @@ export type * from "./configuration.mjs";
 export type * from "./shared-types.mjs";
 export type * from "./cruise-result.mjs";
 export type * from "./resolve-options.mjs";
+export type * from "./environment.mjs";
 
 /**
  * all supported extensions; for each extension whether or not
@@ -15,32 +20,6 @@ export type * from "./resolve-options.mjs";
  */
 export const allExtensions: IAvailableExtension[];
 
-export interface IAvailableExtension {
-	/**
-	 * File extension (e.g. ".js", ".ts", ".jsx")
-	 */
-	extension: string;
-	/**
-	 * Whether or not the extension is available as supported in the current environment
-	 */
-	available: boolean;
-}
-
-export interface IAvailableTranspiler {
-	/**
-	 * The name of the transpiler (e.g. "typescript", "coffeescript")
-	 */
-	name: string;
-	/**
-	 * A semver version range (e.g. ">=2.0.0 <3.0.0")
-	 */
-	version: string;
-	/**
-	 * Whether or not the transpiler is available in the current environment
-	 */
-	available: boolean;
-}
-
 export interface IReporterOutput {
 	/**
 	 * The output proper of the reporter. For most reporters this will be

package/types/environment.d.mts

@@ -0,0 +1,29 @@
+export interface IAvailableExtension {
+	/**
+	 * File extension (e.g. ".js", ".ts", ".jsx")
+	 */
+	extension: string;
+	/**
+	 * Whether or not the extension is available as supported in the current environment
+	 */
+	available: boolean;
+}
+
+export interface IAvailableTranspiler {
+	/**
+	 * The name of the transpiler (e.g. "typescript", "coffeescript")
+	 */
+	name: string;
+	/**
+	 * A semver version range (e.g. ">=2.0.0 <3.0.0")
+	 */
+	version: string;
+	/**
+	 * The currently installed version (e.g. 2.3.4). '-' if not installed
+	 */
+	currentVersion: string;
+	/**
+	 * Whether or not the transpiler is available in the current environment
+	 */
+	available: boolean;
+}

package/types/options.d.mts

@@ -14,10 +14,7 @@ import type { ModuleSystemType, OutputType } from "./shared-types.mjs";
 
 export type ExternalModuleResolutionStrategyType = "node_modules" | "yarn-pnp";
 export type ProgressType =
-	| "cli-feedback"
-	| "performance-log"
-	| "ndjson"
-	| "none";
+	"cli-feedback" | "performance-log" | "ndjson" | "none";
 export type ParserType = "acorn" | "tsc" | "swc";
 
 export interface ITsConfig {

package/types/plugins/3d-reporter-plugin.d.mts

@@ -5,7 +5,7 @@ declare module "3d-reporter-plugin" {
 	 * Sample plugin: 3d representation
 	 *
 	 * @param {ICruiseResult} pCruiseResult - the output of a dependency-cruise adhering to dependency-cruiser's cruise result schema
-	 * @return {IReporterOutput} - output: a string, exitCode: 0
+	 * @returns {IReporterOutput} - output: a string, exitCode: 0
 	 */
 	export default function ThreeDReporterPlugin(
 		pCruiseResult: ICruiseResult,

package/types/plugins/mermaid-reporter-plugin.d.mts

@@ -6,7 +6,7 @@ declare module "mermaid-reporter-plugin" {
 	 *
 	 * @deprecated use the mermaid reporter baked into the dependency-cruiser itself (--output-type mermaid)
 	 * @param {ICruiseResult} pCruiseResult - the output of a dependency-cruise adhering to dependency-cruiser's cruise result schema
-	 * @return {IReporterOutput} - output: the module graph in mermaid format, exitCode: 0
+	 * @returns {IReporterOutput} - output: the module graph in mermaid format, exitCode: 0
 	 */
 	export default function statsReporterPlugin(
 		pCruiseResult: ICruiseResult,

package/types/plugins/stats-reporter-plugin.d.mts

@@ -5,7 +5,7 @@ declare module "stats-reporter-plugin" {
 	 * Sample plugin: stats in json format
 	 *
 	 * @param {ICruiseResult} pCruiseResult - the output of a dependency-cruise adhering to dependency-cruiser's cruise result schema
-	 * @return {IReporterOutput} - output: output: some stats on modules and dependencies in json format, exitCode: 0
+	 * @returns {IReporterOutput} - output: output: some stats on modules and dependencies in json format, exitCode: 0
 	 */
 	export default function statsReporterPlugin(
 		pCruiseResult: ICruiseResult,

package/types/rule-set.d.mts

@@ -128,13 +128,10 @@ export interface IRegularAllowedRuleType {
 }
 
 export type IAllowedRuleType =
-	| IRegularAllowedRuleType
-	| IReachabilityAllowedRuleType;
+	IRegularAllowedRuleType | IReachabilityAllowedRuleType;
 
 export type IAnyRuleType =
-	| IForbiddenRuleType
-	| IAllowedRuleType
-	| IRequiredRuleType;
+	IForbiddenRuleType | IAllowedRuleType | IRequiredRuleType;
 
 export interface IFlattenedRuleSet {
 	/**

package/types/shared-types.d.mts

@@ -75,11 +75,7 @@ export type DependencyType =
 export type ProtocolType = "data:" | "file:" | "node:";
 
 export type ViolationType =
-	| "dependency"
-	| "module"
-	| "cycle"
-	| "reachability"
-	| "instability";
+	"dependency" | "module" | "cycle" | "reachability" | "instability";
 
 export type RuleScopeType = "module" | "folder";
 

package/types/strict-rule-set.d.mts

@@ -54,13 +54,10 @@ export interface IStrictRegularAllowedRuleType extends IRegularAllowedRuleType {
 	to: IStrictToRestriction;
 }
 export type IStrictAllowedRuleType =
-	| IStrictRegularAllowedRuleType
-	| IStrictReachabilityAllowedRuleType;
+	IStrictRegularAllowedRuleType | IStrictReachabilityAllowedRuleType;
 
 export type IStrictAnyRuleType =
-	| IStrictForbiddenRuleType
-	| IStrictAllowedRuleType
-	| IStrictRequiredRuleType;
+	IStrictForbiddenRuleType | IStrictAllowedRuleType | IStrictRequiredRuleType;
 
 export interface IStrictRuleSet extends IFlattenedRuleSet {
 	forbidden?: IStrictForbiddenRuleType[];