dependency-cruiser 18.0.0 → 18.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dependency-cruiser",
-	"version": "18.0.0",
+	"version": "18.1.0",
 	"description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
 	"keywords": [
 		"static analysis",
@@ -149,12 +149,12 @@
 		"acorn-loose": "8.5.2",
 		"acorn-walk": "8.3.5",
 		"commander": "15.0.0",
-		"enhanced-resolve": "5.24.1",
-		"ignore": "7.0.5",
+		"enhanced-resolve": "5.24.2",
+		"ignore": "7.0.6",
 		"interpret": "3.1.1",
 		"is-installed-globally": "1.0.0",
 		"json5": "2.2.3",
-		"picomatch": "4.0.4",
+		"picomatch": "4.0.5",
 		"prompts": "2.4.2",
 		"rechoir": "0.8.0",
 		"safe-regex": "2.1.1",

package/src/analyze/summarize/index.mjs

@@ -1,3 +1,4 @@
+import { EOL } from "node:os";
 import addRuleSetUsed from "./add-rule-set-used.mjs";
 import summarizeModules from "./summarize-modules.mjs";
 import summarizeFolders from "./summarize-folders.mjs";
@@ -8,31 +9,146 @@ import {
 	getDependenciesCruised,
 } from "./get-stats.mjs";
 import { compareViolations } from "#graph-utl/compare.mjs";
+import { getEnvironmentInfo } from "#environment.mjs";
+
+/**
+ * @import { IOptions, IEnvironmentIssue, ISummary, IModule, IFolder } from "../../../types/cruise-result.mjs"
+ * @import { IAvailableTranspiler } from "../../../types/environment.mjs"
+ * @import { IStrictCruiseOptions } from "../../../types/strict-options.mjs"
+ */
+
+/**
+ * @param { IOptions } pOptions
+ * @param { IAvailableTranspiler[] } pAvailableTranspilers
+ * @returns { boolean }
+ */
+function swcIsConsistent(pOptions, pAvailableTranspilers) {
+	const lSWCNeeded = (pOptions?.parser ?? "acorn") === "swc";
+	return lSWCNeeded
+		? pAvailableTranspilers.some(
+				(pTranspiler) => pTranspiler.name === "swc" && pTranspiler.available,
+			)
+		: true;
+}
+
+/**
+ * @param { IOptions } pOptions
+ * @param { IAvailableTranspiler[] } pAvailableTranspilers
+ * @returns { boolean }
+ */
+function typescriptIsConsistent(pOptions, pAvailableTranspilers) {
+	const lTypeScriptNeeded =
+		Boolean(pOptions?.tsConfig) ||
+		Boolean(pOptions?.tsPreCompilationDeps) ||
+		Boolean(pOptions?.detectJSDocImports) ||
+		(pOptions?.parser ?? "acorn") === "tsc";
+	return lTypeScriptNeeded
+		? pAvailableTranspilers.some(
+				(pTranspiler) =>
+					pTranspiler.name === "typescript" && pTranspiler.available,
+			)
+		: true;
+}
+/**
+ * @param { IOptions } pOptions
+ * @param { IAvailableTranspiler[] } pAvailableTranspilers
+ * @returns { boolean }
+ */
+function babelIsConsistent(pOptions, pAvailableTranspilers) {
+	return Boolean(pOptions?.babelConfig)
+		? pAvailableTranspilers.some(
+				(pTranspiler) => pTranspiler.name === "babel" && pTranspiler.available,
+			)
+		: true;
+}
+
+/**
+ * @param {IOptions} pOptions
+ * @param {IAvailableTranspiler[]} pAvailableTranspilers
+ * @returns {{issues?: IEnvironmentIssue[]}}
+ */
+function determineEnvironmentIssues(pOptions, pAvailableTranspilers) {
+	const lIssues = [];
+	if (!typescriptIsConsistent(pOptions, pAvailableTranspilers)) {
+		const tsTranspiler = pAvailableTranspilers.find(
+			(pTranspiler) => pTranspiler.name === "typescript",
+		);
+
+		lIssues.push({
+			severity: "warn",
+			name: "missing-typescript-transpiler",
+			description:
+				`dependency-cruiser detected a TypeScript environment,${EOL}` +
+				`    but not a compatible TypeScript compiler (${tsTranspiler.name}: ${tsTranspiler.version}). This means${EOL}` +
+				`    it's likely to have missed TypeScript sources and dependencies.${EOL}${EOL}` +
+				`    Install typescript to get better results (e.g. npm i -D typescript@^6).${EOL}${EOL}` +
+				`    => Support for typescript@>=7 will follow when its API is published and stable.${EOL}`,
+		});
+	}
+	if (!swcIsConsistent(pOptions, pAvailableTranspilers)) {
+		const swcTranspiler = pAvailableTranspilers.find(
+			(pTranspiler) => pTranspiler.name === "swc",
+		);
+
+		lIssues.push({
+			severity: "warn",
+			name: "missing-swc-transpiler",
+			description:
+				`dependency-cruiser found swc configured as parser, but ${EOL}` +
+				`    it did not find a compatible version of swc (${swcTranspiler.name}: ${swcTranspiler.version}).${EOL}` +
+				`    dependency-cruiser might have missed some sources or dependencies.${EOL}${EOL}` +
+				`    Install swc (e.g. npm i -D @swc/core) to get better results.${EOL}`,
+		});
+	}
+	if (!babelIsConsistent(pOptions, pAvailableTranspilers)) {
+		const babelTranspiler = pAvailableTranspilers.find(
+			(pTranspiler) => pTranspiler.name === "babel",
+		);
+
+		lIssues.push({
+			severity: "warn",
+			name: "missing-babel-transpiler",
+			description:
+				`dependency-cruiser detected a babel configuration, but not a${EOL}` +
+				`    compatible babel transpiler (${babelTranspiler.name}: ${babelTranspiler.version}). If you indeed use babel,${EOL}` +
+				`    dependency-cruiser might have missed some sources or dependencies.${EOL}${EOL}` +
+				`    Install babel (e.g. npm i -D @babel/core@^7) to get better results.${EOL}`,
+		});
+	}
+	return lIssues.length > 0 ? { issues: lIssues } : {};
+}
 
 /**
  *
- * @param {import("../../../types/cruise-result.mjs").IModule[]} pModules -
+ * @param {IModule[]} pModules -
  *    cruised modules that have been enriched with mandatory attributes &
  *    have been validated against rules as passed in the options
- * @param {import("../../../types/options.mjs").IStrictCruiseOptions} pOptions -
+ * @param {IStrictCruiseOptions} pOptions -
  * @param {string[]} pFileDirectoryArray -
  *    the files/ directories originally passed to be cruised
- * @param {import("../../../types/dependency-cruiser.js").IFolder[]} pFolders -
+ * @param {IFolder[]} pFolders -
  *    the pModules collapsed to folders, with their own metrics & deps
  *
- * @returns {import("../../../types/cruise-result.mjs").ISummary} -
+ * @returns {ISummary} -
  *    a summary of the found modules, dependencies and any violations
  */
+// eslint-disable-next-line max-params
 export default function summarize(
 	pModules,
 	pOptions,
 	pFileDirectoryArray,
 	pFolders,
+	pGetEnvironmentInfoFunction = getEnvironmentInfo,
 ) {
 	const lViolations = summarizeModules(pModules, pOptions.ruleSet)
 		.concat(summarizeFolders(pFolders || [], pOptions.ruleSet))
 		.sort(compareViolations);
 
+	const lEnvironment = pGetEnvironmentInfoFunction();
+	const lEnvironmentWithIssues = {
+		...lEnvironment,
+		...determineEnvironmentIssues(pOptions, lEnvironment.transpilersFound),
+	};
 	return {
 		violations: lViolations,
 		...getViolationStats(lViolations),
@@ -40,5 +156,6 @@ export default function summarize(
 		totalDependenciesCruised: getDependenciesCruised(pModules),
 		...summarizeOptions(pFileDirectoryArray, pOptions),
 		...(pOptions.ruleSet ? { ruleSetUsed: addRuleSetUsed(pOptions) } : {}),
+		environment: lEnvironmentWithIssues,
 	};
 }

package/src/cache/cache.mjs

@@ -33,7 +33,7 @@ const EMPTY_CACHE = {
 };
 
 // see ./cache-rationales.md#cache-format-versioning for rationale & bump instructions
-const CACHE_FORMAT_VERSION = 16.2;
+const CACHE_FORMAT_VERSION = 18.1;
 
 export default class Cache {
 	/** @type {(IRevisionData | null)=} */

package/src/cli/format-meta-info.mjs

@@ -1,8 +1,5 @@
-import { release, platform, arch } from "node:os";
 import { styleText } from "node:util";
-
-import { getAvailableTranspilers, allExtensions } from "#main/index.mjs";
-import meta from "#meta.cjs";
+import { getEnvironmentInfo } from "#environment.mjs";
 
 function bool2Symbol(pBool) {
 	return pBool ? styleText("green", "✔") : styleText("red", "x");
@@ -12,13 +9,13 @@ const MAX_VERSION_RANGE_STRING_LENGTH = 19;
 const MAX_TRANSPILER_NAME_LENGTH = 22;
 const MAX_VERSION_STRING_LENGTH = 24;
 
-function formatTranspilers() {
+function formatTranspilers(pAvailableTranspilers) {
 	let lTranspilerTableHeader = styleText(
 		"bold",
 		`    ✔ ${"transpiler".padEnd(MAX_TRANSPILER_NAME_LENGTH)} ${"versions supported".padEnd(MAX_VERSION_RANGE_STRING_LENGTH)} version found`,
 	);
 	let lTranspilerTableDivider = `    - ${"-".repeat(MAX_TRANSPILER_NAME_LENGTH)} ${"-".repeat(MAX_VERSION_RANGE_STRING_LENGTH)} ${"-".repeat(MAX_VERSION_STRING_LENGTH)}`;
-	let lTranspilerTable = getAvailableTranspilers()
+	let lTranspilerTable = pAvailableTranspilers
 		.map(
 			(pTranspiler) =>
 				`    ${bool2Symbol(pTranspiler.available)} ${pTranspiler.name.padEnd(MAX_TRANSPILER_NAME_LENGTH)} ${pTranspiler.version.padEnd(MAX_VERSION_RANGE_STRING_LENGTH)} ${pTranspiler.currentVersion}`,
@@ -36,12 +33,13 @@ function formatExtensions(pExtensions) {
 }
 
 export default function formatMetaInfo() {
+	const lMetaInfo = getEnvironmentInfo();
 	return `
-    ${styleText("bold", "dependency-cruiser")}@${meta.version}
+    ${styleText("bold", "dependency-cruiser")}@${lMetaInfo.version}
 
-    node version supported : ${meta.engines.node}
-    node version found     : ${process.version}
-    os version found       : ${arch()} ${platform()}@${release()}
+    node version supported : ${lMetaInfo.nodeVersionSupported}
+    node version found     : ${lMetaInfo.nodeVersionFound}
+    os version found       : ${lMetaInfo.osVersionFound}
 
     If you need a supported, but not enabled transpiler ('${styleText(
 			"red",
@@ -50,10 +48,10 @@ export default function formatMetaInfo() {
     it in the same folder dependency-cruiser is installed. E.g. 'npm i livescript'
     will enable livescript support if it's installed in your project folder.
 
-${formatTranspilers()}
+${formatTranspilers(lMetaInfo.transpilersFound)}
     ${styleText("bold", "✔ extension")}
     - ---------
-${formatExtensions(allExtensions)}
+${formatExtensions(lMetaInfo.extensionsFound)}
 `;
 }
 

package/src/cli/index.mjs

@@ -135,11 +135,10 @@ async function runCruise(pFileDirectoryArray, pCruiseOptions) {
 /**
  *
  * @param {string[]} pFileDirectoryArray
- * @param {import("../../types/options.mjs").ICruiseOptions} lCruiseOptions
+ * @param {import("../../types/options.mjs").ICruiseOptions} pCruiseOptions
  * @param {{stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream}=} pStreams
  * @returns {number}
  */
-
 // eslint-disable-next-line max-lines-per-function
 export default async function executeCli(
 	pFileDirectoryArray,

package/src/cli/normalize-cli-options.mjs

@@ -196,7 +196,7 @@ function normalizeCache(pCliOptions) {
  *
  * @param  {object} pOptionsAsPassedFromCommander [description]
  * @param {any} pKnownCliOptions [description]
- * @return {object}          [description]
+ * @return {import("../../types/options.mjs").ICruiseOptions}          [description]
  */
 export default async function normalizeOptions(pOptionsAsPassedFromCommander) {
 	let lOptions = {

package/src/environment.mjs

@@ -0,0 +1,17 @@
+import { release, platform, arch } from "node:os";
+import meta from "#meta.cjs";
+import {
+	getAvailableTranspilers,
+	allExtensions,
+} from "#extract/transpile/meta.mjs";
+
+export function getEnvironmentInfo() {
+	return {
+		version: meta.version,
+		nodeVersionSupported: meta.engines.node,
+		nodeVersionFound: process.version,
+		osVersionFound: `${arch()} ${platform()}@${release()}`,
+		transpilersFound: getAvailableTranspilers(),
+		extensionsFound: structuredClone(allExtensions),
+	};
+}

package/src/main/report-wrap.mjs

@@ -39,6 +39,7 @@ function reSummarizeResults(pResult, pFormatOptions) {
 				// TODO: apply filters to the folders too
 				pResult.folders,
 			),
+			environment: pResult.summary.environment,
 		},
 		modules: lModules,
 	};

package/src/meta.cjs

@@ -1,6 +1,6 @@
 /* generated - don't edit */
 module.exports = {
-	version: "18.0.0",
+	version: "18.1.0",
 	engines: {
 		node: "^22||^24||>=26",
 	},

package/src/report/error-html/error-html-template.mjs

@@ -42,6 +42,13 @@ export default `<!DOCTYPE html>
       width: 100%;
     }
 
+    th { 
+      position: sticky; 
+      top: 0; 
+      z-index: 2; 
+      background-color: white 
+    }
+
     th,
     td {
       text-align: left;

package/src/report/error.mjs

@@ -15,6 +15,13 @@ const SEVERITY2COLOR = new Map([
 	["ignore", "gray"],
 ]);
 
+const SEVERITY2ICON = new Map([
+	["error", "x"],
+	["warn", "‼"],
+	["info", "i"],
+	["ignore", "-"],
+]);
+
 const EXTRA_PATH_INFORMATION_INDENT = 6;
 
 function formatMiniDependency(pMiniDependency) {
@@ -116,6 +123,29 @@ function formatIgnoreWarning(pNumberOfIgnoredViolations) {
 	}
 	return "";
 }
+/**
+ * @param {import("../../types/cruise-result.mjs").IEnvironmentIssue} pEnvironmentIssue
+ * @returns {string}
+ */
+function formatEnvironmentIssue(pEnvironmentIssue) {
+	return styleText(
+		SEVERITY2COLOR.get(pEnvironmentIssue.severity),
+		`${SEVERITY2ICON.get(pEnvironmentIssue.severity)} ${styleText("bold", pEnvironmentIssue.name)}: ${pEnvironmentIssue.description}`,
+	);
+}
+
+/**
+ * @param {import("../../types/cruise-result.mjs").IEnvironmentIssue[]} pEnvironmentIssues
+ * @returns {string}
+ */
+function formatEnvironmentIssues(pEnvironmentIssues) {
+	const lEnvironmentIssues = pEnvironmentIssues ?? [];
+
+	return (
+		(lEnvironmentIssues.length > 0 ? EOL : "") +
+		lEnvironmentIssues.map(formatEnvironmentIssue).join(EOL)
+	);
+}
 
 function report(pResults, pOptions) {
 	const lOptions = {
@@ -135,7 +165,7 @@ function report(pResults, pOptions) {
 			pResults.summary.totalDependenciesCruised
 		} dependencies cruised)${EOL}${formatIgnoreWarning(
 			pResults.summary.ignore,
-		)}${EOL}`;
+		)}${formatEnvironmentIssues(pResults.summary.environment?.issues)}${EOL}`;
 	}
 
 	return lNonIgnorableViolations
@@ -147,6 +177,7 @@ function report(pResults, pOptions) {
 		)
 		.concat(formatSummary(pResults.summary))
 		.concat(formatIgnoreWarning(pResults.summary.ignore))
+		.concat(formatEnvironmentIssues(pResults.summary.environment?.issues))
 		.concat(EOL);
 }