dependency-cruiser 18.4.0 → 18.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dependency-cruiser",
-	"version": "18.4.0",
+	"version": "18.5.0",
 	"description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
 	"keywords": [
 		"static analysis",
@@ -149,10 +149,10 @@
 		"acorn-loose": "8.5.2",
 		"acorn-walk": "8.3.5",
 		"commander": "15.0.0",
-		"enhanced-resolve": "5.25.1",
-		"ignore": "7.0.9",
+		"enhanced-resolve": "5.26.0",
+		"ignore": "7.0.11",
 		"interpret": "3.1.1",
-		"is-installed-globally": "1.0.0",
+		"is-installed-globally": "1.0.1",
 		"json5": "2.2.3",
 		"picomatch": "4.0.7",
 		"prompts": "2.4.2",

package/src/analyze/summarize/summarize-options.mjs

@@ -5,6 +5,7 @@ const SHAREABLE_OPTIONS = [
 	"cache",
 	"collapse",
 	"combinedDependencies",
+	"detectImportsInAmbientModules",
 	"detectJSDocImports",
 	"detectProcessBuiltinModuleCalls",
 	"doNotFollow",

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 = 18.1;
+const CACHE_FORMAT_VERSION = 18.5;
 
 export default class Cache {
 	/** @type {(IRevisionData | null)=} */

package/src/cache/options-compatible.mjs

@@ -52,6 +52,8 @@ export function optionsAreCompatible(pOldOptions, pNewOptions) {
 		pOldOptions.preserveSymlinks === pNewOptions.preserveSymlinks &&
 		pOldOptions.combinedDependencies === pNewOptions.combinedDependencies &&
 		pOldOptions.experimentalStats === pNewOptions.experimentalStats &&
+		pOldOptions.detectImportsInAmbientModules ===
+			pNewOptions.detectImportsInAmbientModules &&
 		pOldOptions.detectJSDocImports === pNewOptions.detectJSDocImports &&
 		pOldOptions.detectProcessBuiltinModuleCalls ===
 			pNewOptions.detectProcessBuiltinModuleCalls &&

package/src/cli/init-config/build-config.mjs

@@ -73,6 +73,16 @@ function buildDetectJSDocumentImportsAttribute(pInitOptions) {
 		: "// detectJSDocImports: true,";
 }
 
+/**
+ * @param {IInitConfig} pInitOptions
+ * @returns {string}
+ */
+function buildDetectImportsInAmbientModulesAttribute(pInitOptions) {
+	return pInitOptions.detectImportsInAmbientModules
+		? "detectImportsInAmbientModules: true,"
+		: "// detectImportsInAmbientModules: true,";
+}
+
 /**
  *
  * @param {IInitConfig} pInitOptions
@@ -224,6 +234,10 @@ export default function buildConfig(pInitOptions) {
 			"{{detectJSDocImportsAttribute}}",
 			buildDetectJSDocumentImportsAttribute(pInitOptions),
 		)
+		.replace(
+			"{{detectImportsInAmbientModulesAttribute}}",
+			buildDetectImportsInAmbientModulesAttribute(pInitOptions),
+		)
 		.replace(
 			"{{detectProcessBuiltinModuleCalls}}",
 			buildDetectProcessBuiltinModuleCalls(pInitOptions),

package/src/cli/init-config/config-template.mjs

@@ -227,6 +227,11 @@ module.exports = {
     // to be installed in the same spot you run dependency-cruiser from.
     {{detectJSDocImportsAttribute}}
 
+    // false: don't look at imports in ambient module declarations (the default)
+    // true: detect imports, re-exports and import-equals declarations inside
+    // ambient modules and namespaces. Implies parser: 'tsc'.
+    {{detectImportsInAmbientModulesAttribute}}
+
     // false: don't look at process.getBuiltinModule calls (the default)
     // true: dependency-cruiser will detect calls to process.getBuiltinModule/
     // globalThis.process.getBuiltinModule as imports.

package/src/cli/init-config/environment-helpers.mjs

@@ -105,6 +105,10 @@ export function isLikelyMonoRepo(pFolderNames = getFolderNames(process.cwd())) {
 	return pFolderNames.includes("packages");
 }
 
+/**
+ * @param {Record<string,any>} [pManifest]
+ * @returns
+ */
 function getPackageManager(pManifest) {
 	let lReturnValue = "";
 	try {
@@ -119,7 +123,7 @@ function getPackageManager(pManifest) {
 }
 
 /**
- * @param {Record<string,any>} pManifest
+ * @param {Record<string,any>} [pManifest]
  * @returns {boolean}
  */
 export function likelyUsesBun(pManifest) {

package/src/cli/init-config/get-user-input.mjs

@@ -21,6 +21,10 @@ import {
 import { validateLocation } from "./validators.mjs";
 import { isAvailable as tscIsAvailable } from "#extract/tsc/parse.mjs";
 
+/**
+ * @param {string} pString
+ * @returns {{title:string;value:string}}
+ */
 function toPromptChoice(pString) {
 	return {
 		title: pString,
@@ -116,6 +120,13 @@ const QUESTIONS = [
 		message: "Do you want to detect JSDoc imports (slightly slower)?",
 		initial: false,
 	},
+	{
+		name: "detectImportsInAmbientModules",
+		type: () => (tscIsAvailable() ? "confirm" : false),
+		message:
+			"Do you want to detect imports inside ambient modules (slightly slower)?",
+		initial: false,
+	},
 	{
 		name: "detectProcessBuiltinModuleCalls",
 		type: "confirm",

package/src/cli/init-config/index.mjs

@@ -46,6 +46,7 @@ function getOneShotConfig(pOneShotConfigId) {
 		useTsConfig: hasTSConfigCandidates(),
 		tsConfig: getTSConfigCandidates().shift(),
 		detectJSDocImports: false,
+		detectImportsInAmbientModules: false,
 		detectProcessBuiltinModuleCalls: true,
 		tsPreCompilationDeps: hasTSConfigCandidates(),
 		useWebpackConfig: hasWebpackConfigCandidates(),

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

@@ -20,7 +20,7 @@ function usesTypeScript(pInitOptions, pExtensions) {
 	return Boolean(
 		pInitOptions.tsConfig ||
 		pInitOptions.tsPreCompilationDeps ||
-		(pExtensions || []).some((pExtension) =>
+		(pExtensions /* c8 ignore next */ || []).some((pExtension) =>
 			[".ts", ".tsx", ".d.ts", ".mts", ".d.mts", ".cts", ".d.cts"].includes(
 				pExtension,
 			),

package/src/cli/init-config/types.d.mts

@@ -36,6 +36,10 @@ export interface IInitConfig {
 	 * Whether or not to detect JSDoc imports
 	 */
 	detectJSDocImports?: boolean;
+	/**
+	 * Whether or not to detect imports in ambient module and namespace declarations
+	 */
+	detectImportsInAmbientModules?: boolean;
 	/**
 	 * Whether or not to detect calls to `process.getBuiltinModule`/
 	 * `globalThis.process.getBuiltinModule` as imports

package/src/cli/init-config/write-run-scripts-to-manifest.mjs

@@ -72,8 +72,8 @@ export function compileRunScripts(pInitOptions) {
 
 		lReturnValue = {
 			depcruise: `dependency-cruiser ${lSourceLocations} ${lTestLocations}`,
-			"depcruise:graph": `dependency-cruiser ${lSourceLocations} --include-only '${lSourceLocationRE}' --output-type dot | dot -T svg | depcruise-wrap-stream-in-html > dependency-graph.html`,
-			"depcruise:graph:dev": `dependency-cruiser ${lSourceLocations} --include-only '${lSourceLocationRE}' --prefix vscode://file/$(pwd)/ --output-type dot | dot -T svg | depcruise-wrap-stream-in-html | browser`,
+			"depcruise:graph": `dependency-cruiser ${lSourceLocations} --include-only '${lSourceLocationRE}' --output-type dot-webpage > dependency-graph.html`,
+			"depcruise:graph:dev": `dependency-cruiser ${lSourceLocations} --include-only '${lSourceLocationRE}' --prefix vscode://file/$(pwd)/ --output-type dot-webpage | browser`,
 			"depcruise:graph:archi": `dependency-cruiser ${lSourceLocations} --include-only '${lSourceLocationRE}' --output-type archi | dot -T svg | depcruise-wrap-stream-in-html > high-level-dependency-graph.html`,
 			"depcruise:html": `dependency-cruiser ${lSourceLocations} ${lTestLocations} --progress --output-type err-html --output-to dependency-violation-report.html`,
 			"depcruise:text": `dependency-cruiser ${lSourceLocations} ${lTestLocations} --progress --output-type text`,

package/src/extract/transpile/meta.mjs

@@ -30,8 +30,8 @@ function gotCoffee() {
 		tryImportAvailable(
 			"coffeescript",
 			meta.supportedTranspilers.coffeescript,
+			/* c8 ignore start */
 		) ||
-		/* c8 ignore start */
 		// fallback for ancient versions of the coffeescript compilers
 		tryImportAvailable(
 			"coffee-script",
@@ -96,7 +96,7 @@ export const EXTENSION2AVAILABLE = new Map([
 	[".d.mts", TRANSPILER2AVAILABLE.typescript],
 	[
 		".vue",
-		TRANSPILER2AVAILABLE["vue-template-compiler"] ||
+		TRANSPILER2AVAILABLE["vue-template-compiler"] /* c8 ignore next */ ||
 			TRANSPILER2AVAILABLE["@vue/compiler-sfc"],
 	],
 	[".svelte", TRANSPILER2AVAILABLE.svelte],

package/src/extract/transpile/try-import-available.mjs

@@ -9,7 +9,7 @@ const SCOPED_PACKAGE_RE = "@[^/]+(?:/[^/]+)";
 const ROOT_MODULE_RE = new RegExp(`^(${SCOPED_PACKAGE_RE}|${PACKAGE_RE})`, "g");
 
 function extractRootModuleName(pModuleName) {
-	return (pModuleName.match(ROOT_MODULE_RE) || []).shift();
+	return (pModuleName.match(ROOT_MODULE_RE) || /* c8 ignore next */ []).shift();
 }
 
 function getVersion(pModuleName) {

package/src/extract/tsc/extract-typescript-deps.mjs

@@ -55,11 +55,53 @@ function isTypeOnlyExport(pStatement) {
 }
 
 /*
- * Both extractImport* assume the imports/ exports can only occur at
- * top level. AFAIK this the only place they're allowed, so we should
- * be good. Otherwise we'll need to walk the tree.
+ * The extractImport* below take their statements from getStatements, because
+ * imports and exports are allowed in one place besides the top level: inside a
+ * module block, which is what `declare module "some-package" { ... }` and
+ * `declare namespace Thing { ... }` compile to.
  */
 
+/**
+ * Get the statements of the passed AST node, plus the statements of any module
+ * blocks nested in it
+ *
+ * @param {Node} pAST - an AST node with statements
+ * @returns {Node[]} - the node's statements, flattened over module blocks
+ */
+function getModuleBlock(pStatement) {
+	if (pStatement.kind !== typescript.SyntaxKind.ModuleDeclaration) {
+		return null;
+	}
+
+	// A qualified name nests: `declare namespace A.B {}` is a ModuleDeclaration
+	// whose body is another ModuleDeclaration, and only the innermost one holds
+	// the block.
+	let lBody = pStatement.body;
+
+	while (lBody?.kind === typescript.SyntaxKind.ModuleDeclaration) {
+		lBody = lBody.body;
+	}
+
+	return lBody?.kind === typescript.SyntaxKind.ModuleBlock ? lBody : null;
+}
+
+function getStatements(pAST, pDetectImportsInAmbientModules) {
+	if (!pDetectImportsInAmbientModules) {
+		return pAST.statements ?? [];
+	}
+
+	return (pAST.statements ?? []).flatMap((pStatement) => {
+		const lModuleBlock = getModuleBlock(pStatement);
+
+		return lModuleBlock
+			? [
+					pStatement,
+					...getStatements(lModuleBlock, pDetectImportsInAmbientModules),
+				]
+			: [pStatement];
+	});
+}
+
 /**
  * Get all import statements from the top level AST node
  *
@@ -67,8 +109,8 @@ function isTypeOnlyExport(pStatement) {
  * @returns {{module: string; moduleSystem: string; exoticallyRequired: boolean; dependencyTypes?: string[];}[]} -
  *                                  all import statements in the (top level) AST node
  */
-function extractImports(pAST) {
-	return pAST.statements
+function extractImports(pAST, pDetectImportsInAmbientModules) {
+	return getStatements(pAST, pDetectImportsInAmbientModules)
 		.filter(
 			(pStatement) =>
 				pStatement.kind === typescript.SyntaxKind.ImportDeclaration &&
@@ -91,8 +133,8 @@ function extractImports(pAST) {
  * @returns {{module: string; moduleSystem: string; exoticallyRequired: boolean; dependencyTypes?: string[];}[]} -
  *                                  all export statements in the (top level) AST node
  */
-function extractExports(pAST) {
-	return pAST.statements
+function extractExports(pAST, pDetectImportsInAmbientModules) {
+	return getStatements(pAST, pDetectImportsInAmbientModules)
 		.filter(
 			(pStatement) =>
 				pStatement.kind === typescript.SyntaxKind.ExportDeclaration &&
@@ -119,8 +161,8 @@ function extractExports(pAST) {
  * @returns {{module: string, moduleSystem: string;exoticallyRequired: boolean;}[]} - all import equals statements in the
  *                                  (top level) AST node
  */
-function extractImportEquals(pAST) {
-	return pAST.statements
+function extractImportEquals(pAST, pDetectImportsInAmbientModules) {
+	return getStatements(pAST, pDetectImportsInAmbientModules)
 		.filter(
 			(pStatement) =>
 				pStatement.kind === typescript.SyntaxKind.ImportEqualsDeclaration &&
@@ -562,11 +604,14 @@ export default function extractTypeScriptDependencies(
 	pExoticRequireStrings,
 	pDetectJSDocImports,
 	pDetectProcessBuiltinModuleCalls,
+	pDetectImportsInAmbientModules,
 ) {
 	return typescript
-		? extractImports(pTypeScriptAST)
-				.concat(extractExports(pTypeScriptAST))
-				.concat(extractImportEquals(pTypeScriptAST))
+		? extractImports(pTypeScriptAST, pDetectImportsInAmbientModules)
+				.concat(extractExports(pTypeScriptAST, pDetectImportsInAmbientModules))
+				.concat(
+					extractImportEquals(pTypeScriptAST, pDetectImportsInAmbientModules),
+				)
 				.concat(extractTripleSlashDirectives(pTypeScriptAST))
 				.concat(
 					extractNestedDependencies(

package/src/extract/tsc/extract.mjs

@@ -19,6 +19,7 @@ export function extract(
 		moduleSystems,
 		detectJSDocImports,
 		detectProcessBuiltinModuleCalls,
+		detectImportsInAmbientModules,
 	},
 	pFileName,
 	pTranspileOptions,
@@ -28,6 +29,7 @@ export function extract(
 		exoticRequireStrings,
 		detectJSDocImports,
 		detectProcessBuiltinModuleCalls,
+		detectImportsInAmbientModules,
 	).filter(({ moduleSystem }) => moduleSystems.includes(moduleSystem));
 }
 

package/src/main/options/defaults.mjs

@@ -4,6 +4,7 @@ export default {
 	maxDepth: 0,
 	moduleSystems: ["es6", "cjs", "tsd", "amd"],
 	detectJSDocImports: false,
+	detectImportsInAmbientModules: false,
 	detectProcessBuiltinModuleCalls: false,
 	skipAnalysisNotInRules: false,
 	tsPreCompilationDeps: false,

package/src/main/options/normalize.mjs

@@ -223,7 +223,10 @@ export function normalizeCruiseOptions(pOptions, pFileAndDirectoryArray = []) {
 	if (lReturnValue.cache) {
 		lReturnValue.cache = normalizeCacheOptions(lReturnValue.cache);
 	}
-	if (lReturnValue.detectJSDocImports) {
+	if (
+		lReturnValue.detectJSDocImports ||
+		lReturnValue.detectImportsInAmbientModules
+	) {
 		lReturnValue.parser = "tsc";
 	}
 

package/src/meta.cjs

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

package/src/report/markdown.mjs

@@ -4,7 +4,16 @@ import {
 	determineFromExtras,
 } from "./error-html/utl.mjs";
 import meta from "#meta.cjs";
+import { diffViolationArrays } from "#graph-utl/compare.mjs";
 
+/**
+ * @import { ICruiseResult, IViolation, ISummary } from "../../types/cruise-result.mjs"
+ * @import { IMarkdownReporterOptions } from "../../types/reporter-options.mjs"
+ * @import { IReporterOutput } from "../../types/dependency-cruiser.mjs"
+ * @import { SeverityType } from "../../types/shared-types.mjs"
+ */
+
+/** @type {IMarkdownReporterOptions} */
 const REPORT_DEFAULTS = {
 	showTitle: true,
 	title: "## Forbidden dependency check - results",
@@ -27,6 +36,14 @@ const REPORT_DEFAULTS = {
 	noViolationsMessage:
 		":revolving_hearts: No violations found. Get gummy bears to celebrate.",
 
+	showStaleBaselineDetails: true,
+	staleBaselineHeader: "### :ghost: Stale entries in the baseline",
+	collapseStaleBaseline: true,
+	collapseStaleBaselineMessage:
+		"Stale violations in the baseline - click to expand",
+	staleBaselineIntro:
+		"These violations are in the baseline (typically `.dependency-cruiser-known-violations.json`) but don't match any real violations anymore, e.g. because they were fixed in the meantime. You can remove them with dependency-cruiser's [`--baseline --baseline-mode shrink-only`](https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md#--baseline-create-or-update-a-known-violations-baseline) command line options.",
+
 	showFooter: true,
 	footer: `---\n[dependency-cruiser@${
 		meta.version
@@ -34,7 +51,7 @@ const REPORT_DEFAULTS = {
 };
 
 /**
- * @param {import("../../types/shared-types.js").SeverityType} pSeverity
+ * @param {SeverityType} pSeverity
  * @returns {string}
  */
 function severity2Icon(pSeverity) {
@@ -48,7 +65,7 @@ function severity2Icon(pSeverity) {
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").ISummary} pSummary
+ * @param {ISummary} pSummary
  * @returns {string}
  */
 function formatStatsSummary(pSummary) {
@@ -69,7 +86,7 @@ function formatStatsSummary(pSummary) {
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").ICruiseResult} pCruiseResult
+ * @param {ICruiseResult} pCruiseResult
  * @param {Boolean} pIncludeIgnoredInSummary
  * @returns {string}
  */
@@ -95,9 +112,8 @@ function formatRulesSummary(pCruiseResult, pIncludeIgnoredInSummary) {
 }
 
 /**
- *
- * @param {import("../../types/cruise-result.mjs").IViolation[]} pViolations
- * @param {import("../../types/reporter-options.mjs").IMarkdownReporterOptions} pOptions
+ * @param {IViolation[]} pViolations
+ * @param {IMarkdownReporterOptions} pOptions
  * @returns {string}
  */
 function formatViolations(pViolations, pOptions) {
@@ -119,6 +135,39 @@ function formatViolations(pViolations, pOptions) {
 		}, lTableHead);
 }
 
+/**
+ * @param {IViolation[]} pViolations
+ * @param {IViolation[]} pKnownViolations
+ * @param {IMarkdownReporterOptions} pOptions
+ */
+function staleBaselineDetails(pViolations, pKnownViolations, pOptions) {
+	let lReturnValue = "";
+
+	if (!pKnownViolations) {
+		return lReturnValue;
+	}
+
+	const { old } = diffViolationArrays(pKnownViolations, pViolations);
+
+	if (old.length > 0) {
+		lReturnValue = `${pOptions.staleBaselineHeader}\n\n`;
+		if (pOptions.collapseStaleBaseline) {
+			lReturnValue += `<details><summary>${pOptions.collapseStaleBaselineMessage}</summary>\n\n`;
+		}
+		lReturnValue += `${pOptions.staleBaselineIntro}\n\n`;
+		lReturnValue += `${formatViolations(old, pOptions)}\n\n`;
+		if (pOptions.collapseStaleBaseline) {
+			lReturnValue += `</details>\n\n`;
+		}
+	}
+	return lReturnValue;
+}
+
+/**
+ * @param {IViolation[]} pViolations
+ * @param {IMarkdownReporterOptions} pOptions
+ * @returns {string}
+ */
 function details(pViolations, pOptions) {
 	let lReturnValue = "";
 	if (pViolations.length > 0) {
@@ -138,6 +187,11 @@ function details(pViolations, pOptions) {
 	return lReturnValue;
 }
 
+/**
+ * @param {ICruiseResult} pResults
+ * @param {IMarkdownReporterOptions} pOptions
+ * @returns {string}
+ */
 function summary(pResults, pOptions) {
 	let lReturnValue = "";
 
@@ -156,8 +210,8 @@ function summary(pResults, pOptions) {
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").ICruiseResult} pResults
- * @param {import("../../types/reporter-options.js").IMarkdownReporterOptions} pOptions
+ * @param {ICruiseResult} pResults
+ * @param {IMarkdownReporterOptions} pOptions
  * @returns {string}
  */
 function report(pResults, pOptions) {
@@ -176,6 +230,14 @@ function report(pResults, pOptions) {
 		lReturnValue += details(pResults.summary.violations, lOptions);
 	}
 
+	if (lOptions.showStaleBaselineDetails) {
+		lReturnValue += staleBaselineDetails(
+			pResults.summary.violations,
+			pResults.summary.optionsUsed?.knownViolations,
+			lOptions,
+		);
+	}
+
 	if (lOptions.showFooter) {
 		lReturnValue += `${lOptions.footer}\n\n`;
 	}
@@ -186,9 +248,9 @@ function report(pResults, pOptions) {
 /**
  * Returns the violations from a cruise in markdown format
  *
- * @param {import("../../types/cruise-result.mjs").ICruiseResult} pResults
- * @param {import("../../types/reporter-options.js").IMarkdownReporterOptions} pOptions
- * @returns {import("../../types/dependency-cruiser.js").IReporterOutput}
+ * @param {ICruiseResult} pResults
+ * @param {IMarkdownReporterOptions} pOptions
+ * @returns {IReporterOutput}
  */
 export default function markdown(pResults, pOptions) {
 	return {