dependency-cruiser 18.2.0-beta-2 → 18.3.0

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

@@ -1,5 +1,5 @@
 import { readdirSync, statSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path/posix";
 import ignore from "ignore";
 import pathToPosix from "./path-to-posix.mjs";
 
@@ -7,6 +7,10 @@ import pathToPosix from "./path-to-posix.mjs";
  * @typedef {(pString:string, pIndex: number, pArray: string[]) => boolean} FilterFunctionType
  */
 
+/**
+ * @typedef {{directoryName: string; ignoreMatcher: import("ignore").Ignore}} IgnoreRuleType
+ */
+
 /**
  * @param {string} pFullPathToFile
  * @param {string} pBaseDirectory
@@ -19,18 +23,200 @@ function fileIsDirectory(pFullPathToFile, pBaseDirectory) {
 	return lStat?.isDirectory() ?? false;
 }
 
+/**
+ * @param {string} pFileName
+ * @returns {string}
+ */
+function readIgnoreFile(pFileName) {
+	try {
+		return readFileSync(pFileName, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * @param {string} pDirectoryName
+ * @param {string} pBaseDirectory
+ * @returns {string}
+ */
+function normalizeDirectoryName(pDirectoryName, pBaseDirectory) {
+	return pathToPosix(
+		relative(pBaseDirectory, join(pBaseDirectory, pDirectoryName)),
+	);
+}
+
+/**
+ * @param {string} pDirectoryName
+ * @param {string} pIgnoreFileContents
+ * @param {string[]=} pAdditionalIgnorePatterns
+ * @returns {IgnoreRuleType}
+ */
+function createIgnoreRule(
+	pDirectoryName,
+	pIgnoreFileContents,
+	pAdditionalIgnorePatterns = [],
+) {
+	return {
+		directoryName: pDirectoryName,
+		ignoreMatcher: ignore()
+			.add(pIgnoreFileContents)
+			.add(pAdditionalIgnorePatterns),
+	};
+}
+
 /**
  * @param {string} pDirectoryName
- * @param {{baseDir: string; ignoreFilterFn: FilterFunctionType; excludeFilterFn: FilterFunctionType; includeOnlyFilterFn: FilterFunctionType}} pOptions
+ * @param {string} pBaseDirectory
+ * @param {{ignoreFileContents?: string}} pOptions
+ * @returns {IgnoreRuleType}
+ */
+function createIgnoreRuleForDirectory(
+	pDirectoryName,
+	pBaseDirectory,
+	pOptions,
+) {
+	const lIgnoreFileContents =
+		pOptions.ignoreFileContents === undefined
+			? readIgnoreFile(join(pBaseDirectory, pDirectoryName, ".gitignore"))
+			: pOptions.ignoreFileContents;
+
+	return createIgnoreRule(pDirectoryName, lIgnoreFileContents);
+}
+
+/**
+ * @param {string[]} pAncestorDirectoryNames
+ * @param {string} pBaseDirectory
+ * @returns {IgnoreRuleType[]}
+ */
+function createIgnoreRulesFromDirectoryNames(
+	pAncestorDirectoryNames,
+	pBaseDirectory,
+) {
+	return pAncestorDirectoryNames.map((pAncestorDirectoryName) =>
+		createIgnoreRuleForDirectory(pAncestorDirectoryName, pBaseDirectory, {}),
+	);
+}
+
+/**
+ * @param {string} pDirectoryName
+ * @param {string} pBaseDirectory
+ * @returns {IgnoreRuleType[]}
+ */
+function createIgnoreRulesBeforeDirectory(pDirectoryName, pBaseDirectory) {
+	const lNormalizedDirectoryName = normalizeDirectoryName(
+		pDirectoryName,
+		pBaseDirectory,
+	);
+
+	if (lNormalizedDirectoryName === "") {
+		return [];
+	}
+
+	const lDirectorySegments = lNormalizedDirectoryName.split("/");
+	const lAncestorDirectoryNames = [""];
+	let lCurrentDirectoryName = "";
+
+	for (const lDirectorySegment of lDirectorySegments.slice(0, -1)) {
+		lCurrentDirectoryName = lCurrentDirectoryName
+			? join(lCurrentDirectoryName, lDirectorySegment)
+			: lDirectorySegment;
+		lAncestorDirectoryNames.push(pathToPosix(lCurrentDirectoryName));
+	}
+
+	return createIgnoreRulesFromDirectoryNames(
+		lAncestorDirectoryNames,
+		pBaseDirectory,
+	);
+}
+
+/**
+ * @param {string} pFilePath
+ * @param {IgnoreRuleType[]} pIgnoreRules
+ * @param {IgnoreRuleType} pMandatoryIgnoreRule
+ * @returns {boolean}
+ */
+function fileShouldBeKept(pFilePath, pIgnoreRules, pMandatoryIgnoreRule) {
+	let lFileIsIgnored = false;
+
+	for (const lIgnoreRule of pIgnoreRules) {
+		const lDirectoryName = lIgnoreRule.directoryName;
+		const lIgnoreMatcher = lIgnoreRule.ignoreMatcher;
+		let lRelativePath = null;
+
+		if (lDirectoryName === "") {
+			lRelativePath = pFilePath;
+		} else if (pFilePath.startsWith(`${lDirectoryName}/`)) {
+			lRelativePath = pFilePath.slice(lDirectoryName.length + 1);
+		}
+
+		if (lRelativePath !== null) {
+			const { ignored: lIgnored, unignored: lUnignored } =
+				lIgnoreMatcher.test(lRelativePath);
+
+			if (lIgnored) {
+				lFileIsIgnored = true;
+			}
+			if (lUnignored) {
+				lFileIsIgnored = false;
+			}
+		}
+	}
+
+	const { ignored: lIgnored, unignored: lUnignored } =
+		pMandatoryIgnoreRule.ignoreMatcher.test(pFilePath);
+
+	if (lIgnored) {
+		lFileIsIgnored = true;
+	}
+	if (lUnignored) {
+		lFileIsIgnored = false;
+	}
+
+	return !lFileIsIgnored;
+}
+
+/**
+ * @type FilterFunctionType
+ */
+
+function identityFilter(_pString, _pIndex, _pArray) {
+	return true;
+}
+
+/**
+ * @param {string} pDirectoryName
+ * @param {{baseDir: string; ignoreRules: IgnoreRuleType[]; mandatoryIgnoreRule: IgnoreRuleType; startDirectoryName: string; startDirectoryIgnoreFileContents?: string; excludeFilterFn: FilterFunctionType; includeOnlyFilterFn: FilterFunctionType}}
+ *   pOptions
  * @returns {string[]}
  */
 function walk(
 	pDirectoryName,
-	{ baseDir, ignoreFilterFn, excludeFilterFn, includeOnlyFilterFn },
+	{
+		baseDir,
+		ignoreRules,
+		mandatoryIgnoreRule,
+		startDirectoryName,
+		startDirectoryIgnoreFileContents,
+		excludeFilterFn,
+		includeOnlyFilterFn,
+	},
 ) {
+	const lCurrentDirectoryName = normalizeDirectoryName(pDirectoryName, baseDir);
+	const lCurrentIgnoreRules = ignoreRules.concat(
+		createIgnoreRuleForDirectory(lCurrentDirectoryName, baseDir, {
+			...(lCurrentDirectoryName === startDirectoryName &&
+			startDirectoryIgnoreFileContents !== undefined
+				? { ignoreFileContents: startDirectoryIgnoreFileContents }
+				: {}),
+		}),
+	);
+
 	const lFilesInCurrentDirectory = readdirSync(join(baseDir, pDirectoryName))
 		.map((pFileName) => join(pDirectoryName, pFileName))
-		.filter(ignoreFilterFn)
+		.filter((pFilePath) =>
+			fileShouldBeKept(pFilePath, lCurrentIgnoreRules, mandatoryIgnoreRule),
+		)
 		.filter(excludeFilterFn)
 		.filter(includeOnlyFilterFn);
 
@@ -40,7 +226,10 @@ function walk(
 			lFiles.push(
 				...walk(lFile, {
 					baseDir,
-					ignoreFilterFn,
+					ignoreRules: lCurrentIgnoreRules,
+					mandatoryIgnoreRule,
+					startDirectoryName,
+					startDirectoryIgnoreFileContents,
 					excludeFilterFn,
 					includeOnlyFilterFn,
 				}),
@@ -53,25 +242,10 @@ function walk(
 	return lFiles;
 }
 
-function readIgnoreFile(pFileName) {
-	try {
-		return readFileSync(pFileName, "utf8");
-	} catch {
-		return "";
-	}
-}
-
-/**
- * @type FilterFunctionType
- */
-
-function identityFilter(_pString, _pIndex, _pArray) {
-	return true;
-}
-
 /**
  * @param {string} pDirectoryName
- * @param {{baseDir: string; ignoreFileContents?: string; additionalIgnorePatterns?: string[]; excludeFilterFn?: FilterFunctionType; includeOnlyFilterFn?: FilterFunctionType}} pOptions
+ * @param {{baseDir: string; ignoreFileContents?: string; additionalIgnorePatterns?: string[]; excludeFilterFn?: FilterFunctionType; includeOnlyFilterFn?: FilterFunctionType}}
+ *   pOptions
  * @returns {string[]}
  */
 export default function findAllFiles(
@@ -84,17 +258,24 @@ export default function findAllFiles(
 		includeOnlyFilterFn,
 	},
 ) {
-	const lIgnoreFileContents =
-		ignoreFileContents ?? readIgnoreFile(join(baseDir, ".gitignore"));
 	const lAdditionalIgnorePatterns = additionalIgnorePatterns ?? [".git"];
-	const lIgnoreFilterFunction = ignore()
-		.add(lIgnoreFileContents)
-		.add(lAdditionalIgnorePatterns)
-		.createFilter();
+	const lStartDirectoryName = normalizeDirectoryName(pDirectoryName, baseDir);
+	const lMandatoryIgnoreRule = createIgnoreRule(
+		"",
+		"",
+		lAdditionalIgnorePatterns,
+	);
+	const lIgnoreRules = createIgnoreRulesBeforeDirectory(
+		pDirectoryName,
+		baseDir,
+	);
 
 	return walk(pDirectoryName, {
 		baseDir,
-		ignoreFilterFn: lIgnoreFilterFunction,
+		ignoreRules: lIgnoreRules,
+		mandatoryIgnoreRule: lMandatoryIgnoreRule,
+		startDirectoryName: lStartDirectoryName,
+		startDirectoryIgnoreFileContents: ignoreFileContents,
 		excludeFilterFn: excludeFilterFn ?? identityFilter,
 		includeOnlyFilterFn: includeOnlyFilterFn ?? identityFilter,
 	});

package/src/utl/try-import.mjs

@@ -14,7 +14,7 @@ function getVersion(pModuleName) {
 	// The 'proper' way to do this would be with a dynamic import with an
 	// import assertion. Because it's 'experimental' since node 16 and prints
 	// an ugly warning on stderr since node 19 we'll be using the require
-	// hack below in stead. Code would otherwise have been:
+	// hack below instead. Code would otherwise have been:
 	//
 	// const lManifest = await import(
 	//   // @ts-expect-error TS2345 extractRootModuleName can return either a string or

package/types/dependency-cruiser.d.mts

@@ -26,6 +26,12 @@ export interface IReporterOutput {
 	 * a string.
 	 */
 	output: ICruiseResult | string;
+	/**
+	 * Textual meta information to show in a side-channel (like stderr). E.g.
+	 * the baseline reporter returns the numerical diffs between the current
+	 * and the new baseline.
+	 */
+	meta?: string;
 	/**
 	 * The exit code - reporters can return a non-zero value when they find
 	 * errors here. api consumers (like a cli) can use this to return a

package/types/options.d.mts

@@ -16,6 +16,7 @@ export type ExternalModuleResolutionStrategyType = "node_modules" | "yarn-pnp";
 export type ProgressType =
 	"cli-feedback" | "performance-log" | "ndjson" | "none";
 export type ParserType = "acorn" | "tsc" | "swc";
+export type BaselineModeType = "full" | "shrink-only";
 
 export interface ITsConfig {
 	fileName?: string;
@@ -109,6 +110,11 @@ export interface ICruiseOptions {
 	 * as 'highlighted' in its output
 	 */
 	highlight?: string | string[] | IHighlightType;
+	/*
+	 * whether or not to ignore known violations (whether passed in a separate
+	 * file or directly in knownViolations)
+	 */
+	ignoreKnown?: boolean;
 	/*
 	 * baseline of known validations. Typically you'd specify these in a file called
 	 * .dependency-cruiser-known-violations.json (which you'd generate with the --outputType
@@ -234,7 +240,7 @@ export interface ICruiseOptions {
 	 *
 	 * Hasn't had any effect on dependency-cruiser's behaviour since a few major
 	 * versions ago. If there's a need to manipulate this use the `skipAnalysisNotInRules`
-	 * option in stead.
+	 * option instead.
 	 *
 	 * Previously documented behavior:
 	 * > When true includes denormalized dependents in the cruise-result, even
@@ -424,6 +430,16 @@ export interface ICruiseOptions {
 	 * When caching is switched on the default cache folder is 'node_modules/.cache/dependency-cruiser/'
 	 */
 	cache?: boolean | string | Partial<ICacheOptions>;
+
+	baseline?: {
+		/**
+		 * How to update the baseline;
+		 * 'full' - replaces all violations with the current set (the default behaviour)
+		 * 'shrink-only' - keeps existing violations, removes fixed violations, but
+		 *  does not add new ones.
+		 */
+		mode?: BaselineModeType;
+	};
 }
 
 export interface IFormatOptions {

package/types/restrictions.d.mts

@@ -84,13 +84,13 @@ export interface IToRestriction extends IBaseRestrictionType {
 	 * _only_ modules that don't satisfy this regular expression. E.g. to disallow all cycles,
 	 * except when they go through one specific module. Typically to temporarily
 	 * allow some cycles until they're removed.
-	 * @deprecated use viaOnly.pathNot in stead
+	 * @deprecated use viaOnly.pathNot instead
 	 */
 	viaNot?: string | string[];
 	/**
 	 * "For circular dependencies - whether or not to match cycles that include
 	 * _some_ modules that don't satisfy this regular expression.
-	 * @deprecated use via.pathNot in stead
+	 * @deprecated use via.pathNot instead
 	 */
 	viaSomeNot?: string | string[];
 	/**

package/types/shared-types.d.mts

@@ -3,26 +3,29 @@ export type ModuleSystemType = "cjs" | "amd" | "es6" | "tsd";
 
 // cruise options, dependency-cruiser
 export type OutputType =
-	| "json"
-	| "html"
-	| "dot"
-	| "cdot"
+	| "anon"
 	| "archi"
+	| "azure-devops"
+	| "baseline"
+	| "cdot"
+	| "csv"
+	| "d2"
 	| "ddot"
+	| "dot-webpage"
+	| "dot"
+	| "err-html"
+	| "err-long"
+	| "err"
 	| "fdot"
 	| "flat"
-	| "csv"
-	| "err"
-	| "err-long"
-	| "err-html"
-	| "teamcity"
-	| "anon"
-	| "text"
-	| "metrics"
+	| "html"
+	| "json"
 	| "markdown"
 	| "mermaid"
-	| "d2"
+	| "metrics"
 	| "null"
+	| "teamcity"
+	| "text"
 	// for plugins: string. TODO: research whether it's possible to
 	// tie this down to the `^plugin:[^:]+-reporter-plugin.[cm]?js$` regex
 	| (string & {}); // autocompletion hack