dependency-cruiser 18.2.0 → 18.3.0

package/src/graph-utl/compare.mjs

@@ -1,14 +1,14 @@
 /** @import { IViolation } from "../../types/dependency-cruiser.mjs" */
 /* eslint-disable no-magic-numbers */
+const SEVERITY2MUMBER = new Map([
+	["error", 1],
+	["warn", 2],
+	["info", 3],
+	["ignore", 4],
+]);
+
 function severity2number(pSeverity) {
-	const lSeverity2Number = new Map([
-		["error", 1],
-		["warn", 2],
-		["info", 3],
-		["ignore", 4],
-	]);
-
-	return lSeverity2Number.get(pSeverity) || -1;
+	return SEVERITY2MUMBER.get(pSeverity) || -1;
 }
 
 export function compareSeverities(pFirstSeverity, pSecondSeverity) {
@@ -71,15 +71,21 @@ function compareArrays(pFirstArray, pSecondArray) {
  *
  * @param {IViolation} pFirstViolation
  * @param {IViolation} pSecondViolation
- * @returns
+ * @param {boolean} pCompareSeverities
+ * @returns {number}
  */
 // eslint-disable-next-line complexity
-export function compareViolations(pFirstViolation, pSecondViolation) {
+function compareViolationsBase(
+	pFirstViolation,
+	pSecondViolation,
+	pCompareSeverities,
+) {
 	return (
-		compareSeverities(
-			pFirstViolation.rule.severity,
-			pSecondViolation.rule.severity,
-		) ||
+		(pCompareSeverities &&
+			compareSeverities(
+				pFirstViolation.rule.severity,
+				pSecondViolation.rule.severity,
+			)) ||
 		pFirstViolation.rule.name.localeCompare(pSecondViolation.rule.name) ||
 		pFirstViolation.from.localeCompare(pSecondViolation.from) ||
 		pFirstViolation.to.localeCompare(pSecondViolation.to) ||
@@ -96,6 +102,99 @@ export function compareViolations(pFirstViolation, pSecondViolation) {
 	);
 }
 
+/**
+ * Compares violations on all relevant fields _excluding_ severity
+ *
+ * @param {IViolation} pFirstViolation
+ * @param {IViolation} pSecondViolation
+ * @returns {number}
+ */
+export function compareViolationsExSeverities(
+	pFirstViolation,
+	pSecondViolation,
+) {
+	return compareViolationsBase(pFirstViolation, pSecondViolation, false);
+}
+
+/**
+ * Compares violations on all relevant fields _including_ severity
+ *
+ * @param {IViolation} pFirstViolation
+ * @param {IViolation} pSecondViolation
+ * @returns {number}
+ */
+export function compareViolations(pFirstViolation, pSecondViolation) {
+	return compareViolationsBase(pFirstViolation, pSecondViolation, true);
+}
+
+/**
+ * Compare two arrays of violations and return a diff by value.
+ *
+ * Use the project’s established scalar ordering, compareViolations(),
+ * rather than introducing a second comparison construct. This keeps the
+ * semantics in one place and makes the diff logic easier to maintain.
+ *
+ * @param {IViolation[]} pFirstViolationArray - First array of violations
+ * @param {IViolation[]} pSecondViolationArray - Second array of violations
+ * @returns {{
+ *   new: IViolation[]; // only in the second array
+ *   same: IViolation[]; // in both arrays
+ *   old: IViolation[]; // only in the first array
+ * }}
+ */
+export function diffViolationArrays(
+	pFirstViolationArray,
+	pSecondViolationArray,
+) {
+	const lFirstViolations = pFirstViolationArray.toSorted(
+		compareViolationsExSeverities,
+	);
+	const lSecondViolations = pSecondViolationArray.toSorted(
+		compareViolationsExSeverities,
+	);
+	const lNew = [];
+	const lSame = [];
+	const lOld = [];
+	let lFirstIndex = 0;
+	let lSecondIndex = 0;
+
+	while (
+		lFirstIndex < lFirstViolations.length ||
+		lSecondIndex < lSecondViolations.length
+	) {
+		if (lFirstIndex >= lFirstViolations.length) {
+			lNew.push(lSecondViolations[lSecondIndex]);
+			lSecondIndex += 1;
+			continue;
+		}
+
+		if (lSecondIndex >= lSecondViolations.length) {
+			lOld.push(lFirstViolations[lFirstIndex]);
+			lFirstIndex += 1;
+			continue;
+		}
+
+		const lComparison = compareViolationsExSeverities(
+			lFirstViolations[lFirstIndex],
+			lSecondViolations[lSecondIndex],
+		);
+
+		if (lComparison === 0) {
+			lSame.push(lFirstViolations[lFirstIndex]);
+			lFirstIndex += 1;
+			lSecondIndex += 1;
+		} else if (lComparison < 0) {
+			lOld.push(lFirstViolations[lFirstIndex]);
+			lFirstIndex += 1;
+		} else {
+			lNew.push(lSecondViolations[lSecondIndex]);
+			lSecondIndex += 1;
+		}
+	}
+
+	return { new: lNew, same: lSame, old: lOld };
+}
+
 export function compareRules(pLeftRule, pRightRule) {
 	return (
 		compareSeverities(pLeftRule.severity, pRightRule.severity) ||

package/src/main/options/normalize.mjs

@@ -4,7 +4,6 @@ import defaults from "./defaults.mjs";
 import { uniq } from "#utl/array-util.mjs";
 
 /**
- * @import { ICruiseResult } from "../../../types/cruise-result.mjs";
  * @import { ICruiseOptions, IFormatOptions } from "../../../types/options.mjs";
  * @import { IStrictCruiseOptions, IStrictFormatOptions } from "../../../types/strict-options.mjs";
  * @import { IForbiddenRuleType, IFlattenedRuleSet } from "../../../types/rule-set.mjs";
@@ -115,6 +114,13 @@ function ruleSetHasMetricsRule(pRuleSet) {
 	);
 }
 
+// TODO duplicated in ../report-wrap.mjs
+function getReporterSection(pOutputType) {
+	return ["x-dot-webpage", "dot-webpage"].includes(pOutputType)
+		? "dot"
+		: pOutputType;
+}
+
 /**
  *
  * @param {ICruiseOptions} pOptions
@@ -122,8 +128,8 @@ function ruleSetHasMetricsRule(pRuleSet) {
  */
 function reporterShowsMetrics(pOptions) {
 	return (
-		(pOptions.reporterOptions?.[pOptions?.outputType]?.showMetrics ?? false) ===
-		true
+		(pOptions.reporterOptions?.[getReporterSection(pOptions?.outputType)]
+			?.showMetrics ?? false) === true
 	);
 }
 

package/src/main/report-wrap.mjs

@@ -44,9 +44,11 @@ function reSummarizeResults(pResult, pFormatOptions) {
 		modules: lModules,
 	};
 }
-
+// TODO duplicated in ./options/normalize.mjs
 function getReporterSection(pOutputType) {
-	return pOutputType === "x-dot-webpage" ? "dot" : pOutputType;
+	return ["x-dot-webpage", "dot-webpage"].includes(pOutputType)
+		? "dot"
+		: pOutputType;
 }
 
 /**

package/src/meta.cjs

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

package/src/report/baseline.mjs

@@ -1,24 +1,66 @@
+import { diffViolationArrays } from "#graph-utl/compare.mjs";
+/**
+ * @import { ICruiseResult, IReporterOutput } from "../../types/dependency-cruiser.mjs";
+ * @import { IViolation} from "../../types/violations.mjs"
+ * @import { BaselineModeType } from "../../types/options.mjs"
+ */
+
 const DEFAULT_JSON_INDENT = 2;
 const EOL = "\n";
+const BASELINE_DEFAULT_MODE = "full";
+
+/**
+ * @param {IViolation[]} pKnownViolations
+ * @param {IViolation[]} pCurrentViolations
+ * @param {BaselineModeType} pMode
+ * @returns {IReporterOutput}
+ */
+function getBaseline(pKnownViolations, pCurrentViolations, pMode) {
+	const lReturnValue = {};
+	const lKnownViolations = pKnownViolations || [];
+	const lViolationArrayDiff = diffViolationArrays(
+		lKnownViolations,
+		pCurrentViolations,
+	);
+	let lViolationsToEmit = pCurrentViolations;
+	let lModeAddition = " (running in 'full' mode => added to the baseline)";
+
+	if (pMode === "shrink-only") {
+		lViolationsToEmit = lViolationArrayDiff.same;
+		lModeAddition =
+			" (running in 'shrink-only' mode => not added to the baseline)";
+	}
+	lReturnValue.meta =
+		`${EOL}baseline  : ${lViolationsToEmit.length} violations${EOL}${EOL}` +
+		`  new     : ${lViolationArrayDiff.new.length}${lViolationArrayDiff.new.length > 0 ? lModeAddition : ""}${EOL}` +
+		`  same    : ${lViolationArrayDiff.same.length}${EOL}` +
+		`  removed : ${lViolationArrayDiff.old.length}${EOL}`;
+	lReturnValue.output =
+		JSON.stringify(lViolationsToEmit, null, DEFAULT_JSON_INDENT) + EOL;
+
+	return lReturnValue;
+}
 
 /**
- * Sample plugin
+ * Returns the current 'baseline' of violations, which can be used
  *
- * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult -
+ * @param {ICruiseResult} pCruiseResult -
  *      the output of a dependency-cruise adhering to dependency-cruiser's
  *      cruise result schema
- * @returns {import('../../types/dependency-cruiser').IReporterOutput} -
- *      output: some stats on modules and dependencies in json format
+ * @returns {IReporterOutput} -
+ *      output: known violations
+ *      meta: information to print on a side channel (e.g. stderr)
  *      exitCode: 0
  */
 export default function baseline(pCruiseResult) {
+	const { meta, output } = getBaseline(
+		pCruiseResult.summary.optionsUsed.knownViolations,
+		pCruiseResult.summary.violations,
+		pCruiseResult.summary.optionsUsed?.baseline?.mode ?? BASELINE_DEFAULT_MODE,
+	);
 	return {
-		output:
-			JSON.stringify(
-				pCruiseResult.summary.violations,
-				null,
-				DEFAULT_JSON_INDENT,
-			) + EOL,
+		output,
+		meta,
 		exitCode: 0,
 	};
 }

package/src/report/dot-webpage/dot-module.mjs

@@ -63,7 +63,7 @@ function isAvailable(pOptions) {
 export default function dotWebpage(pResults, pDotWebpageReporterOptions) {
 	if (!isAvailable(pDotWebpageReporterOptions)) {
 		throw new Error(
-			"GraphViz dot, which is required for the 'x-dot-webpage' reporter doesn't " +
+			"GraphViz dot, which is required for the 'dot-webpage' reporter doesn't " +
 				"seem to be available on this system. See the GraphViz download page for " +
 				"instruction on how to get it on your system: https://www.graphviz.org/download/",
 		);

package/src/report/index.mjs

@@ -23,6 +23,7 @@ const TYPE2MODULE = new Map([
 	["null", "./null.mjs"],
 	["teamcity", "./teamcity.mjs"],
 	["text", "./text.mjs"],
+	["dot-webpage", "./dot-webpage/dot-module.mjs"],
 	["x-dot-webpage", "./dot-webpage/dot-module.mjs"],
 ]);