dependency-cruiser 18.3.1 → 18.5.0

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

@@ -6,6 +6,12 @@ import {
 import template from "./error-html-template.mjs";
 import meta from "#meta.cjs";
 import { getOneLetterDependencyType } from "#report/utl/index.mjs";
+import { diffViolationArrays } from "#graph-utl/compare.mjs";
+/**
+ * @import { ICruiseResult, IViolation } from "../../../types/cruise-result.mjs"
+ * @import { IErrorReporterOptions } from "../../../types/reporter-options.mjs"
+ * @import {  IReporterOutput } from "../../../types/dependency-cruiser.mjs"
+ */
 
 function getViolatedRuleRowClass(pViolatedRule) {
 	return pViolatedRule.unviolated ? ' class="unviolated"' : "";
@@ -34,7 +40,7 @@ function buildViolatedRuleRow(pViolatedRule) {
 }
 
 /**
- * @param {import('../../../types/cruise-result.mjs')} pResults
+ * @param {ICruiseResult} pResults
  * @returns {string}
  */
 function constructViolatedRulesTable(pResults) {
@@ -71,15 +77,17 @@ function constructViolatedRulesTable(pResults) {
 }
 
 /**
- * @param {import('../../../types/cruise-result.mjs').IViolation} pViolation
+ * @param {IViolation} pViolation
  * @returns {string}
  */
 function getViolationRowClass(pViolation) {
 	return pViolation.rule.severity === "ignore" ? ' class="ignored"' : "";
 }
+
 /**
- * @param {import('../../../types/cruise-result.mjs').IViolation} pViolation
- * @returns {string}
+ * @param {string} pPrefix
+ * @param {IErrorReporterOptions} pOptions
+ * @returns {(pViolation: IViolation) => string}
  */
 function constructViolationRow(pPrefix, pOptions) {
 	return (pViolation) => {
@@ -101,7 +109,8 @@ function constructViolationRow(pPrefix, pOptions) {
 }
 
 /**
- * @param {import('../../../types/cruise-result.mjs').ICruiseResult} pResults
+ * @param {ICruiseResult} pResults
+ * @param {IErrorReporterOptions} pOptions
  * @returns {string}
  */
 function constructViolationsList(pResults, pOptions) {
@@ -154,7 +163,68 @@ function constructViolationsList(pResults, pOptions) {
 }
 
 /**
- * @param {import('../../../types/cruise-result.mjs')} pResults
+ * @param {number} pBaselineStaleCount
+ * @returns {string}
+ */
+function constructStaleDiv(pBaselineStaleCount) {
+	if ((pBaselineStaleCount ?? 0) > 0) {
+		return `<div style="float:left;padding-right:20px" class="ignore">
+    <strong>${pBaselineStaleCount}</strong> stale entries in baseline
+    </div>`;
+	}
+	return "";
+}
+
+/**
+ * @param {ICruiseResult} pResults
+ * @param {IErrorReporterOptions} pOptions
+ * @returns {string}
+ */
+function constructBaselineStaleTable(pResults, pOptions) {
+	if ((pResults.summary.baselineStale ?? 0) > 0) {
+		const { old } = diffViolationArrays(
+			pResults.summary.optionsUsed.knownViolations,
+			pResults.summary.violations,
+		);
+		return `<span id="stale-baseline-entries">
+      <h2><svg class="p__svg--inline" viewBox="144 144 512 512" version="1.1" aria-hidden="true"><path d="M583.48 299.64a202 202 0 0 0-108.32-109.58 194.4 194.4 0 0 0-150.29 0 202.3 202.3 0 0 0-123.43 186.4v224.26a25.2 25.2 0 0 0 5.04 14.7q4.46.63 8.96.61c8.52.2 16.98-1.52 24.74-5.04a89 89 0 0 0 26.8-22.57c2.57-2.82 5.04-5.54 7.66-8.06 3.6-3.67 7.7-6.84 12.14-9.42a41 41 0 0 1 20.81-5.04c19.75 0 29.43 10.53 40.6 22.73a101 101 0 0 0 22.58 20.15 63 63 0 0 0 4.48 2.42 60.4 60.4 0 0 0 49.48 0q2.33-1.08 4.43-2.37c8.5-5.54 16.1-12.34 22.57-20.15 11.18-12.2 20.86-22.73 40.6-22.73A41 41 0 0 1 513.2 571a58 58 0 0 1 12.15 9.42 132 132 0 0 1 7.65 8.07 89 89 0 0 0 27 22.36 57 57 0 0 0 24.75 5.04q4.53 0 9.01-.6c3.2-4.25 4.95-9.4 5.04-14.71v-224.1a202 202 0 0 0-15.32-76.83zm0 124.74v176.33c-18.9-.45-28.41-10.73-39.35-22.67-2.42-2.62-5.04-5.34-7.5-7.96a83 83 0 0 0-11.44-9.73 55.4 55.4 0 0 0-32.8-10.07c-26.4 0-39.9 14.71-51.74 27.66s-20.9 23.02-40.65 23.02-29.43-10.53-40.61-22.72-25.2-27.66-51.74-27.66a55.4 55.4 0 0 0-32.75 10.08 83 83 0 0 0-11.44 9.72c-2.62 2.62-5.04 5.34-7.56 7.96-10.93 11.94-20.45 22.17-39.3 22.67V376.46c0-102.78 82.33-186.4 183.5-186.4 101.16 0 183.49 83.63 183.49 186.4z"/><path d="M511.69 280.75a59.6 59.6 0 1 0 59.6 63.83q.4-3.98 0-7.95a59.55 59.55 0 0 0-59.6-55.88m-44.53 59.65a44.45 44.45 0 0 1 66.1-38.84h-.91a38.92 38.92 0 0 0 0 77.84h.9a44.45 44.45 0 0 1-66.1-38.84zm-38.59-3.98a59.6 59.6 0 1 0 0 7.96q.4-3.99 0-7.96m-104.14 3.98a44.44 44.44 0 0 1 66.1-38.84h-.6a38.91 38.91 0 1 0 0 77.84h.9a44.45 44.45 0 0 1-66.4-39"/>
+    </svg> Stale entries in the baseline</h2>
+    <p>
+      These violations are in the baseline (typically <tt>.dependency-cruiser-known-violations.json</tt>), 
+      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 
+      <a href="https://github.com/sverweij/dependency-cruiser/blob/main/doc/cli.md#--baseline-create-or-update-a-known-violations-baseline"><tt>--baseline --baseline-mode shrink-only</tt>
+      command line options</a>.
+    </p>
+    <table>
+      <thead>
+        <tr>
+          <th>severity</th>
+          <th>rule</th>
+          <th>from</th>
+          <th>types</th>
+          <th>to</th>
+        </tr>
+      </thead>
+      <tbody>
+      ${old
+				.map(
+					constructViolationRow(
+						pResults.summary.optionsUsed.prefix ?? "",
+						pOptions,
+					),
+				)
+				.join("\n")}
+      </tbody>
+    </table>
+    </span>`;
+	}
+	return "";
+}
+
+/**
+ * @param {ICruiseResult} pResults
+ * @param {IErrorReporterOptions} pOptions
  * @returns {string}
  */
 function report(pResults, pOptions) {
@@ -173,8 +243,13 @@ function report(pResults, pOptions) {
 		.replace("{{warn}}", pResults.summary.warn)
 		.replace("{{info}}", pResults.summary.info)
 		.replace("{{ignore}}", pResults.summary.ignore ?? 0)
+		.replace("{{staleDiv}}", constructStaleDiv(pResults.summary.baselineStale))
 		.replace("{{violatedRulesTable}}", constructViolatedRulesTable(pResults))
 		.replace("{{violationsList}}", constructViolationsList(pResults, lOptions))
+		.replace(
+			"{{baselineStaleTable}}",
+			constructBaselineStaleTable(pResults, pOptions),
+		)
 		.replace("{{depcruiseVersion}}", `dependency-cruiser@${meta.version}`)
 		.replace("{{runDate}}", new Date().toISOString());
 }
@@ -182,8 +257,9 @@ function report(pResults, pOptions) {
 /**
  * Returns the results of a cruise in an 'incidence matrix'
  *
- * @param {import("../../../types/cruise-result.mjs").ICruiseResult} pResults - the output of a dependency-cruise adhering to ../../schema/cruise-result.schema.json
- * @returns {import("../../../types/dependency-cruiser.js").IReporterOutput} - output: an html program showing the summary & the violations (if any)
+ * @param {ICruiseResult} pResults - the output of a dependency-cruise adhering to ../../schema/cruise-result.schema.json
+ * @param {IErrorReporterOptions} pOptions
+ * @returns {IReporterOutput} - output: an html program showing the summary & the violations (if any)
  *                              exitCode: 0
  */
 export default function errorHtml(pResults, pOptions) {

package/src/report/error.mjs

@@ -8,6 +8,13 @@ import {
 import { findRuleByName } from "#graph-utl/rule-set.mjs";
 import wrapAndIndent from "#utl/wrap-and-indent.mjs";
 
+/**
+ * @import { ICruiseResult, IEnvironmentIssue } from "../../types/cruise-result.mjs"
+ * @import { IErrorReporterOptions } from "../../types/reporter-options.mjs"
+ * @import { IReporterOutput } from "../../types/dependency-cruiser.js"
+ * @import { SeverityType } from "../../types/shared-types.mjs"
+ */
+
 const SEVERITY2COLOR = new Map([
 	["error", "red"],
 	["warn", "yellow"],
@@ -114,6 +121,10 @@ function addExplanation(pRuleSet, pLong) {
 		: (pViolation) => pViolation;
 }
 
+/**
+ * @param {number} pNumberOfIgnoredViolations
+ * @returns {string}
+ */
 function formatIgnoreWarning(pNumberOfIgnoredViolations) {
 	if (pNumberOfIgnoredViolations > 0) {
 		return styleText(
@@ -123,8 +134,9 @@ function formatIgnoreWarning(pNumberOfIgnoredViolations) {
 	}
 	return "";
 }
+
 /**
- * @param {import("../../types/cruise-result.mjs").IEnvironmentIssue} pEnvironmentIssue
+ * @param {IEnvironmentIssue} pEnvironmentIssue
  * @returns {string}
  */
 function formatEnvironmentIssue(pEnvironmentIssue) {
@@ -135,7 +147,7 @@ function formatEnvironmentIssue(pEnvironmentIssue) {
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").IEnvironmentIssue[]} pEnvironmentIssues
+ * @param {IEnvironmentIssue[]} pEnvironmentIssues
  * @returns {string}
  */
 function formatEnvironmentIssues(pEnvironmentIssues) {
@@ -147,6 +159,30 @@ function formatEnvironmentIssues(pEnvironmentIssues) {
 	);
 }
 
+/**
+ * @param {number} pBaselineStaleCount
+ * @param {SeverityType} pStaleEntriesSeverity
+ * @returns {string}
+ */
+function formatStaleBaselineMessage(
+	pBaselineStaleCount,
+	pStaleEntriesSeverity,
+) {
+	if ((pBaselineStaleCount ?? 0) > 0) {
+		const lStaleEntriesSeverity = pStaleEntriesSeverity ?? "warn";
+		return styleText(
+			SEVERITY2COLOR.get(lStaleEntriesSeverity),
+			`${SEVERITY2ICON.get(lStaleEntriesSeverity)} ${pBaselineStaleCount} stale known violations in the baseline. Run with '--baseline --baseline-mode shrink-only' to remove them.${EOL}`,
+		);
+	}
+	return "";
+}
+
+/**
+ * @param {ICruiseResult} pResults
+ * @param {IErrorReporterOptions} pOptions
+ * @returns {string}
+ */
 function report(pResults, pOptions) {
 	const lOptions = {
 		long: false,
@@ -163,13 +199,20 @@ function report(pResults, pOptions) {
 			pResults.summary.totalCruised
 		} modules, ${
 			pResults.summary.totalDependenciesCruised
-		} dependencies cruised)${EOL}${formatIgnoreWarning(
-			pResults.summary.ignore,
-		)}${formatEnvironmentIssues(pResults.summary.environment?.issues)}${EOL}`;
+		} dependencies cruised)${EOL}`
+			.concat(formatIgnoreWarning(pResults.summary.ignore))
+			.concat(
+				formatStaleBaselineMessage(
+					pResults.summary.baselineStale,
+					pResults.summary.optionsUsed?.baseline?.staleEntriesSeverity,
+				),
+			)
+			.concat(formatEnvironmentIssues(pResults.summary.environment?.issues))
+			.concat(EOL);
 	}
 
 	return lNonIgnorableViolations
-		.reverse()
+		.toReversed()
 		.map(addExplanation(pResults.summary.ruleSetUsed, lOptions.long))
 		.reduce(
 			(pAll, pThis) => `${pAll}  ${formatViolation(pThis, lOptions)}${EOL}`,
@@ -177,6 +220,12 @@ function report(pResults, pOptions) {
 		)
 		.concat(formatSummary(pResults.summary))
 		.concat(formatIgnoreWarning(pResults.summary.ignore))
+		.concat(
+			formatStaleBaselineMessage(
+				pResults.summary.baselineStale,
+				pResults.summary.optionsUsed?.baseline?.staleEntriesSeverity,
+			),
+		)
 		.concat(formatEnvironmentIssues(pResults.summary.environment?.issues))
 		.concat(EOL);
 }
@@ -187,16 +236,16 @@ function report(pResults, pOptions) {
  * - for each violation a message stating the violation name and the to and from
  * - a summary with total number of errors and warnings found, and the total
  *   number of files cruised
- * @param {import("../../types/cruise-result.mjs").ICruiseResult} pResults -
- * @param {any} pOptions - An object with options;
- *                         {boolean} long - whether or not to include an explanation
- *                                          (/ comment) which each violation
- * @returns {import("../../types/dependency-cruiser.js").IReporterOutput} - output: the formatted text in a string
- *                              exitCode: the number of errors found
+ * @param {ICruiseResult} pResults
+ * @param {IErrorReporterOptions} pOptions
+ * @returns {IReporterOutput}
  */
 export default function error(pResults, pOptions) {
 	return {
 		output: report(pResults, pOptions || {}),
-		exitCode: pResults.summary.error,
+		// advisedExitCode is a mandatory attribute as of dependency-cruiser 18.4.0
+		// however, this reporter can still encounter dependency-cruiser results
+		// from before that, hence the fallback
+		exitCode: pResults.summary.advisedExitCode ?? pResults.summary.error,
 	};
 }

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,17 +65,28 @@ function severity2Icon(pSeverity) {
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").ISummary} pSummary
+ * @param {ISummary} pSummary
  * @returns {string}
  */
 function formatStatsSummary(pSummary) {
 	const lSpacerLength = 4;
 	const lSpacer = " ".repeat(lSpacerLength);
-	return `**${pSummary.totalCruised}** modules${lSpacer}**${pSummary.totalDependenciesCruised}** dependencies${lSpacer}**${pSummary.error}** errors${lSpacer}**${pSummary.warn}** warnings${lSpacer}**${pSummary.info}** informational${lSpacer}**${pSummary.ignore}** ignored\n`;
+	return `**${pSummary.totalCruised}** modules${lSpacer}`
+		.concat(`**${pSummary.totalDependenciesCruised}** dependencies${lSpacer}`)
+		.concat(`**${pSummary.error}** errors${lSpacer}`)
+		.concat(`**${pSummary.warn}** warnings${lSpacer}`)
+		.concat(`**${pSummary.info}** informational${lSpacer}`)
+		.concat(`**${pSummary.ignore}** ignored`)
+		.concat(
+			(pSummary.baselineStale ?? 0) > 0
+				? `${lSpacer}**${pSummary.baselineStale}** stale entries in baseline`
+				: "",
+		)
+		.concat("\n");
 }
 
 /**
- * @param {import("../../types/cruise-result.mjs").ICruiseResult} pCruiseResult
+ * @param {ICruiseResult} pCruiseResult
  * @param {Boolean} pIncludeIgnoredInSummary
  * @returns {string}
  */
@@ -84,9 +112,8 @@ function formatRulesSummary(pCruiseResult, pIncludeIgnoredInSummary) {
 }
 
 /**
- *
- * @param {import("../../types/cruise-result.mjs").IViolation[]} pViolations
- * @param {object} pOptions
+ * @param {IViolation[]} pViolations
+ * @param {IMarkdownReporterOptions} pOptions
  * @returns {string}
  */
 function formatViolations(pViolations, pOptions) {
@@ -108,19 +135,49 @@ function formatViolations(pViolations, pOptions) {
 		}, lTableHead);
 }
 
-function details(pResults, pOptions) {
+/**
+ * @param {IViolation[]} pViolations
+ * @param {IViolation[]} pKnownViolations
+ * @param {IMarkdownReporterOptions} pOptions
+ */
+function staleBaselineDetails(pViolations, pKnownViolations, pOptions) {
 	let lReturnValue = "";
-	if (pResults.summary.violations.length > 0) {
+
+	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) {
 		if (pOptions.showDetailsHeader) {
 			lReturnValue += `${pOptions.detailsHeader}\n\n`;
 		}
 		if (pOptions.collapseDetails) {
 			lReturnValue += `<details><summary>${pOptions.collapsedMessage}</summary>\n\n`;
 		}
-		lReturnValue += `${formatViolations(
-			pResults.summary.violations,
-			pOptions,
-		)}\n\n`;
+		lReturnValue += `${formatViolations(pViolations, pOptions)}\n\n`;
 		if (pOptions.collapseDetails) {
 			lReturnValue += "</details>\n\n";
 		}
@@ -130,6 +187,11 @@ function details(pResults, pOptions) {
 	return lReturnValue;
 }
 
+/**
+ * @param {ICruiseResult} pResults
+ * @param {IMarkdownReporterOptions} pOptions
+ * @returns {string}
+ */
 function summary(pResults, pOptions) {
 	let lReturnValue = "";
 
@@ -148,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) {
@@ -165,7 +227,15 @@ function report(pResults, pOptions) {
 	}
 
 	if (lOptions.showDetails) {
-		lReturnValue += details(pResults, lOptions);
+		lReturnValue += details(pResults.summary.violations, lOptions);
+	}
+
+	if (lOptions.showStaleBaselineDetails) {
+		lReturnValue += staleBaselineDetails(
+			pResults.summary.violations,
+			pResults.summary.optionsUsed?.knownViolations,
+			lOptions,
+		);
 	}
 
 	if (lOptions.showFooter) {
@@ -178,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 {

package/src/report/null.mjs

@@ -1,12 +1,15 @@
 /**
  * Returns the results of a cruise _only_ in an exitCode
  *
- * @param {import("../../types/cruise-result").ICruiseResult} pResults
- * @returns {import("../../types/dependency-cruiser").IReporterOutput}
+ * @param {import("../../types/cruise-result.mjs").ICruiseResult} pResults
+ * @returns {import("../../types/dependency-cruiser.mjs").IReporterOutput}
  */
 export default function nullReporter(pResults) {
 	return {
 		output: "",
-		exitCode: pResults.summary.error,
+		// advisedExitCode is a mandatory attribute as of dependency-cruiser 18.4.0
+		// however, this reporter can still encounter dependency-cruiser results
+		// from before that, hence the fallback
+		exitCode: pResults.summary.advisedExitCode ?? pResults.summary.error,
 	};
 }

package/src/report/teamcity.mjs

@@ -273,6 +273,9 @@ export default function teamcity(pResults) {
 			reportViolatedRules(lRuleSet, lViolations, lIgnoredCount, lFlowId)
 				.concat(reportViolations(lViolations, lIgnoredCount, lFlowId))
 				.reduce((pAll, pCurrent) => `${pAll}${pCurrent}${EOL}`, "") || EOL,
-		exitCode: pResults.summary.error,
+		// advisedExitCode is a mandatory attribute as of dependency-cruiser 18.4.0
+		// however, this reporter can still encounter dependency-cruiser results
+		// from before that, hence the fallback
+		exitCode: pResults.summary.advisedExitCode ?? pResults.summary.error,
 	};
 }