dependency-cruiser 16.1.0 → 16.2.0

package/bin/dependency-cruise.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { EOL } from "node:os";
-import { program } from "commander";
+import { program, Option } from "commander";
 import assertNodeEnvironmentSuitable from "#cli/assert-node-environment-suitable.mjs";
 import cli from "#cli/index.mjs";
 import meta from "#meta.js";
@@ -22,7 +22,7 @@ try {
       true,
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--no-config",
         "do not use a configuration file. " +
           "Overrides any --config option set earlier",
@@ -34,7 +34,7 @@ try {
       "err",
     )
     .option("-m, --metrics", "calculate stability metrics", false)
-    .addOption(new program.Option("--no-metrics").hideHelp(true))
+    .addOption(new Option("--no-metrics").hideHelp(true))
     .option(
       "-f, --output-to <file>",
       "file to write output to; - for stdout",
@@ -71,21 +71,21 @@ try {
       "--ignore-known [file]",
       "ignore known violations as saved in [file] (default: .dependency-cruiser-known-violations.json)",
     )
-    .addOption(new program.Option("--no-ignore-known").hideHelp(true))
+    .addOption(new Option("--no-ignore-known").hideHelp(true))
     .addOption(
-      new program.Option(
+      new Option(
         "--ts-config [file]",
         "use a TypeScript configuration (e.g. tsconfig.json) or it's JavaScript counterpart (e.g. jsconfig.json)",
       ).hideHelp(true),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--webpack-config [file]",
         "use a webpack configuration (e.g. webpack.config.js)",
       ).hideHelp(true),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--ts-pre-compilation-deps",
         "detect dependencies that only exist before typescript-to-javascript " +
           "compilation (off by default)",
@@ -98,25 +98,23 @@ try {
         "modules/ folders directly under your packages folder. ",
     )
     .addOption(
-      new program.Option(
+      new Option(
         "-p, --progress [type]",
         "show progress while dependency-cruiser is busy",
       ).choices(["cli-feedback", "performance-log", "ndjson", "none"]),
     )
     .addOption(
-      new program.Option("--no-progress", "Alias of --progress none").hideHelp(
-        true,
-      ),
+      new Option("--no-progress", "Alias of --progress none").hideHelp(true),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "-d, --max-depth <n>",
-        "You probably want to use --collapse instead of --max-depth. " +
+        "you probably want to use --collapse instead of --max-depth. " +
           "(max-depth would limit the cruise depth; 0 <= n <= 99 (default: 0 - no limit)).",
       ).hideHelp(true),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "-M, --module-systems <items>",
         "list of module systems (default: amd, cjs, es6, tsd)",
       ).hideHelp(true),
@@ -127,33 +125,30 @@ try {
     )
     .option(
       "-C, --cache [cache-directory]",
-      "(experimental) use a cache to speed up execution. " +
+      "use a cache to speed up execution. " +
         "The directory defaults to node_modules/.cache/dependency-cruiser",
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--cache-strategy <strategy>",
-        "(experimental) strategy to use for detecting changed files in the cache.",
+        "strategy to use for detecting changed files in the cache.",
       ).choices(["metadata", "content"]),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--no-cache",
         "switch off caching. Overrides the 'cache' key in .dependency-cruiser.js " +
           "and --cache options set earlier on the command line",
       ).hideHelp(true),
     )
     .addOption(
-      new program.Option(
+      new Option(
         "--preserve-symlinks",
         "leave symlinks unchanged (off by default)",
       ).hideHelp(true),
     )
     .addOption(
-      new program.Option(
-        "-v, --validate [file]",
-        `alias for --config`,
-      ).hideHelp(true),
+      new Option("-v, --validate [file]", `alias for --config`).hideHelp(true),
     )
     .option(
       "-i, --info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "16.1.0",
+  "version": "16.2.0",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -106,10 +106,10 @@
     "acorn-walk": "8.3.2",
     "ajv": "8.12.0",
     "chalk": "5.3.0",
-    "commander": "11.1.0",
+    "commander": "12.0.0",
     "enhanced-resolve": "5.15.0",
     "figures": "6.0.1",
-    "ignore": "5.3.0",
+    "ignore": "5.3.1",
     "indent-string": "5.0.0",
     "interpret": "^3.1.1",
     "is-installed-globally": "1.0.0",

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

@@ -50,7 +50,7 @@ function getOneShotConfig(pOneShotConfigId) {
   const lOneShotConfigs = new Map([
     ["yes", lBaseConfig],
     [
-      "experimental-scripts",
+      "x-scripts",
       {
         updateManifest: fileExists(PACKAGE_MANIFEST),
         ...lBaseConfig,

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

@@ -1,4 +1,4 @@
-export type OneShotConfigIDType = "yes" | "experimental-scripts";
+export type OneShotConfigIDType = "yes" | "x-scripts";
 
 export interface IInitConfig {
   /**

package/src/cli/tools/wrap-stream-in-html.mjs

@@ -1,53 +1,20 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { getHeader, getFooter } from "#report/dot-webpage/wrap-in-html.mjs";
 
 const STYLESHEET_FILE = fileURLToPath(
-  new URL("svg-in-html-snippets/style.css", import.meta.url),
+  new URL(
+    "../../report/dot-webpage/svg-in-html-snippets/style.css",
+    import.meta.url,
+  ),
 );
 const SCRIPT_FILE = fileURLToPath(
-  new URL("svg-in-html-snippets/script.js", import.meta.url),
+  new URL(
+    "../../report/dot-webpage/svg-in-html-snippets/script.js",
+    import.meta.url,
+  ),
 );
 
-/**
- * @param {string} pStylesheet
- * @returns {string}
- */
-function getHeader(pStylesheet) {
-  return `<!doctype html>
-<html lang="en" dir="ltr">
-  <head>
-    <meta charset="utf-8" />
-    <title>dependency graph</title>
-    <style>
-      ${pStylesheet}
-    </style>
-  </head>
-  <body>
-    <button id="button_help">?</button>
-    <div id="hints" class="hint" style="display: none">
-      <button id="close-hints">x</button>
-      <span id="hint-text"></span>
-      <ul>
-        <li><b>Hover</b> - highlight</li>
-        <li><b>Right-click</b> - pin highlight</li>
-        <li><b>ESC</b> - clear</li>
-      </ul>
-    </div>
-`;
-}
-
-/**
- * @param {string} pScript
- * @returns {string}
- */
-function getFooter(pScript) {
-  return `    <script>
-      ${pScript}
-    </script>
-  </body>
-</html>`;
-}
-
 /**
  * Slaps the stuff in the passed stream in between the contents
  * of the header and the footer and returns it as a string.

package/src/cli/utl/io.mjs

@@ -40,13 +40,15 @@ function writeToStdOut(pString, pBufferSize = PIPE_BUFFER_SIZE) {
   }
 }
 export function write(pOutputTo, pContent) {
-  const lContentWithTrailingNewline = pContent.endsWith("\n")
-    ? pContent
-    : `${pContent}\n`;
+  // previously we checked here to ensure pContent ended on an EOL (and if it
+  // didn't we added one). As for one or two reporters we DON'T want this
+  // to happen automatically (e.g. the 'null' one) we've moved that check
+  // to the individual reporters and with a unit test ensured that all
+  // reporters (current and future) keep doing that.
   if ("-" === pOutputTo) {
-    writeToStdOut(lContentWithTrailingNewline);
+    writeToStdOut(pContent);
   } else {
-    writeToFile(pOutputTo, lContentWithTrailingNewline);
+    writeToFile(pOutputTo, pContent);
   }
 }
 

package/src/meta.js

@@ -1,7 +1,7 @@
 /* generated - don't edit */
 
 module.exports = {
-  version: "16.1.0",
+  version: "16.2.0",
   engines: {
     node: "^18.17||>=20",
   },

package/src/report/anon/index.mjs

@@ -1,6 +1,8 @@
 import has from "lodash/has.js";
 import { anonymizePath, WHITELIST_RE } from "./anonymize-path.mjs";
 
+const EOL = "\n";
+
 function anonymizePathArray(pPathArray, pWordList) {
   // the coverage ignore is here because the || [] branch isn't taken when running
   // tests and with the current setup of the anonymize module that's not going
@@ -182,11 +184,15 @@ export default function reportAnonymous(pResults, pAnonymousReporterOptions) {
       pResults?.summary?.optionsUsed?.reporterOptions?.anon?.wordlist ?? [];
   }
   return {
-    output: JSON.stringify(
-      anonymize(pResults, sanitizeWordList(lAnonymousReporterOptions.wordlist)),
-      null,
-      "  ",
-    ),
+    output:
+      JSON.stringify(
+        anonymize(
+          pResults,
+          sanitizeWordList(lAnonymousReporterOptions.wordlist),
+        ),
+        null,
+        "  ",
+      ) + EOL,
     exitCode: 0,
   };
 }

package/src/report/baseline.mjs

@@ -1,4 +1,5 @@
 const DEFAULT_JSON_INDENT = 2;
+const EOL = "\n";
 
 /**
  * Sample plugin
@@ -12,11 +13,12 @@ const DEFAULT_JSON_INDENT = 2;
  */
 export default function baseline(pCruiseResult) {
   return {
-    output: JSON.stringify(
-      pCruiseResult.summary.violations,
-      null,
-      DEFAULT_JSON_INDENT
-    ),
+    output:
+      JSON.stringify(
+        pCruiseResult.summary.violations,
+        null,
+        DEFAULT_JSON_INDENT,
+      ) + EOL,
     exitCode: 0,
   };
 }

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

@@ -0,0 +1,77 @@
+// @ts-check
+import { spawnSync } from "node:child_process";
+import dotModuleReporter from "../dot/dot-module.mjs";
+import { wrapInHTML } from "./wrap-in-html.mjs";
+
+const CONSTANTS = {
+  exec: "dot",
+  format: "svg",
+};
+
+/**
+ * @param {string} pDot Dot program
+ * @param {IDotWebpageReporterOptions} pOptions
+ * @returns {string} the dot program converted to svg, wrapped in html
+ */
+function convert(pDot, pOptions) {
+  /* c8 ignore next */
+  const lSpawnFunction = pOptions.spawnFunction || spawnSync;
+  const { stdout, status, error } = lSpawnFunction(
+    CONSTANTS.exec,
+    [`-T${CONSTANTS.format}`],
+    {
+      input: pDot,
+    },
+  );
+  if (status === 0) {
+    return stdout.toString("binary");
+  } else if (error) {
+    throw error;
+  } else {
+    throw new Error(`GraphViz' dot returned an error (exit code ${status})`);
+  }
+}
+
+/**
+ * @param {IDotWebpageReporterOptions} pOptions
+ * @returns {boolean}
+ */
+function isAvailable(pOptions) {
+  /* c8 ignore next */
+  const lSpawnFunction = pOptions.spawnFunction || spawnSync;
+  const { status, stderr } = lSpawnFunction(CONSTANTS.exec, ["-V"]);
+  return (
+    status === 0 && stderr.toString("utf8").startsWith("dot - graphviz version")
+  );
+}
+
+/**
+ * @typedef {import("../../../types/cruise-result.mjs").ICruiseResult} ICruiseResult
+ * @typedef {import("../../../types/reporter-options.mjs").IDotReporterOptions} IDotReporterOptions
+ * @typedef {import("../../../types/dependency-cruiser.mjs").IReporterOutput} IReporterOutput
+ * @typedef {IDotReporterOptions & { spawnFunction?: typeof spawnSync }} IDotWebpageReporterOptions
+ */
+
+/**
+ * Returns the results of a cruise as an svg picture, using the dot reporter
+ * and a system call to the GraphViz dot executable.
+ *
+ * @param {ICruiseResult} pResults
+ * @param {IDotWebpageReporterOptions} pDotWebpageReporterOptions
+ * @returns {IReporterOutput}
+ */
+export default function dotWebpage(pResults, pDotWebpageReporterOptions) {
+  const { output } = dotModuleReporter(pResults, pDotWebpageReporterOptions);
+
+  if (!isAvailable(pDotWebpageReporterOptions)) {
+    throw new Error(
+      "GraphViz dot, which is required for the 'x-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/",
+    );
+  }
+  return {
+    output: wrapInHTML(convert(output, pDotWebpageReporterOptions)),
+    exitCode: 0,
+  };
+}

package/src/report/dot-webpage/wrap-in-html.mjs

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const STYLESHEET_FILE = fileURLToPath(
+  new URL("svg-in-html-snippets/style.css", import.meta.url),
+);
+const SCRIPT_FILE = fileURLToPath(
+  new URL("svg-in-html-snippets/script.js", import.meta.url),
+);
+
+/**
+ * @param {string} pStylesheet
+ * @returns {string}
+ */
+export function getHeader(pStylesheet) {
+  return `<!doctype html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="utf-8" />
+    <title>dependency graph</title>
+    <style>
+      ${pStylesheet}
+    </style>
+  </head>
+  <body>
+    <button id="button_help">?</button>
+    <div id="hints" class="hint" style="display: none">
+      <button id="close-hints">x</button>
+      <span id="hint-text"></span>
+      <ul>
+        <li><b>Hover</b> - highlight</li>
+        <li><b>Right-click</b> - pin highlight</li>
+        <li><b>ESC</b> - clear</li>
+      </ul>
+    </div>
+`;
+}
+
+/**
+ * @param {string} pScript
+ * @returns {string}
+ */
+export function getFooter(pScript) {
+  return `    <script>
+      ${pScript}
+    </script>
+  </body>
+</html>
+`;
+}
+
+/**
+ *
+ * @param {string} pSVG
+ * @returns {string}
+ */
+export function wrapInHTML(pSVG) {
+  const lStylesheet = readFileSync(STYLESHEET_FILE, "utf8");
+  const lScript = readFileSync(SCRIPT_FILE, "utf8");
+
+  return getHeader(lStylesheet) + pSVG + getFooter(lScript);
+}

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

@@ -209,4 +209,5 @@ export default `<!DOCTYPE html>
       {{runDate}}</p>
   </footer>
 </body>
-</html>`;
+</html>
+`;

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

@@ -181,4 +181,5 @@ export default `<!DOCTYPE html>
 <body>
   {{table-here}}
 </body>
-</html>`;
+</html>
+`;

package/src/report/index.mjs

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

package/src/report/json.mjs

@@ -1,3 +1,4 @@
+const EOL = "\n";
 /**
  * Returns the results of a cruise in JSON
  *
@@ -6,7 +7,7 @@
  */
 export default function json(pResults) {
   return {
-    output: JSON.stringify(pResults, null, "  "),
+    output: JSON.stringify(pResults, null, "  ") + EOL,
     exitCode: 0,
   };
 }

package/src/report/teamcity.mjs

@@ -7,6 +7,7 @@ const SEVERITY2TEAMCITY_SEVERITY = new Map([
   ["warn", "WARNING"],
   ["info", "INFO"],
 ]);
+const EOL = "\n";
 
 function severity2teamcitySeverity(pSeverity) {
   return SEVERITY2TEAMCITY_SEVERITY.get(pSeverity) || "INFO";
@@ -159,9 +160,10 @@ export default function teamcity(pResults) {
   const lIgnoredCount = pResults?.summary?.ignore ?? 0;
 
   return {
-    output: reportViolatedRules(lRuleSet, lViolations, lIgnoredCount)
-      .concat(reportViolations(lViolations, lIgnoredCount))
-      .reduce((pAll, pCurrent) => `${pAll}${pCurrent}\n`, ""),
+    output:
+      reportViolatedRules(lRuleSet, lViolations, lIgnoredCount)
+        .concat(reportViolations(lViolations, lIgnoredCount))
+        .reduce((pAll, pCurrent) => `${pAll}${pCurrent}\n`, "") || EOL,
     exitCode: pResults.summary.error,
   };
 }

package/src/report/text.mjs

@@ -1,10 +1,10 @@
-import { EOL } from "node:os";
 import figures from "figures";
 import chalk from "chalk";
 
 const DEFAULT_OPTIONS = {
   highlightFocused: false,
 };
+const EOL = "\n";
 
 /**
  *
@@ -30,9 +30,9 @@ function toFlatDependencies(pModules, pModulesInFocus, pHighlightFocused) {
   return pModules.reduce(
     (pAll, pModule) =>
       pAll.concat(
-        toFlatModuleDependencies(pModule, pModulesInFocus, pHighlightFocused)
+        toFlatModuleDependencies(pModule, pModulesInFocus, pHighlightFocused),
       ),
-    []
+    [],
   );
 }
 
@@ -55,7 +55,7 @@ function getModulesInFocus(pModules) {
   return new Set(
     pModules
       .filter((pModule) => pModule.matchesFocus || pModule.matchesReaches)
-      .map((pModule) => pModule.source)
+      .map((pModule) => pModule.source),
   );
 }
 
@@ -68,13 +68,15 @@ function getModulesInFocus(pModules) {
 function report(pResults, pOptions) {
   const lOptions = { ...DEFAULT_OPTIONS, ...pOptions };
 
-  return toFlatDependencies(
-    pResults.modules,
-    getModulesInFocus(pResults.modules),
-    lOptions.highlightFocused === true
-  ).reduce(
-    (pAll, pDependency) => pAll.concat(stringify(pDependency)).concat(EOL),
-    ""
+  return (
+    toFlatDependencies(
+      pResults.modules,
+      getModulesInFocus(pResults.modules),
+      lOptions.highlightFocused === true,
+    ).reduce(
+      (pAll, pDependency) => pAll.concat(stringify(pDependency)).concat(EOL),
+      "",
+    ) || EOL
   );
 }
 

package/types/restrictions.d.mts

@@ -173,7 +173,6 @@ export interface IDependentsModuleRestrictionType extends IBaseRestrictionType {
    * Matches when the number of times the 'to' module is used falls below (<)
    * this number. Caveat: only works in concert with path and pathNot restrictions
    * in the from and to parts of the rule; other conditions will be ignored.
-   * (somewhat experimental; - syntax can change over time without a major bump)
    * E.g. to flag modules that are used only once or not at all, use 2 here.
    */
   numberOfDependentsLessThan?: number;
@@ -181,7 +180,6 @@ export interface IDependentsModuleRestrictionType extends IBaseRestrictionType {
    * Matches when the number of times the 'to' module is used rises above (<)
    * this number. Caveat: only works in concert with path and pathNot restrictions
    * in the from and to parts of the rule; other conditions will be ignored.
-   * (somewhat experimental; - syntax can change over time without a major bump)
    * E.g. to flag modules that are used more than 10 times, use 10 here.
    */
   numberOfDependentsMoreThan?: number;

package/types/rule-set.d.mts

@@ -43,13 +43,10 @@ export interface IRegularForbiddenRuleType extends IBaseRuleType {
   /**
    * What to apply the rule to - modules (the default) or folders. Switching
    * the scope to 'folder' can be useful in rules where this makes a difference
-   * like those regarding circular dependencies or instability. Two things
-   * to note when you decide to use 'folder' level scope: (1) the 'scope' attribute
-   * is experimental - the way to indicate the scope of a rule can change
-   * over time without dependency-cruiser undergoing a major bump. (2) Only
-   * the to.moreUnstable, to.circular, and path (both from and to) attributes
-   * work at the moment. Other attributes will follow suit in releases
-   * after 11.6.0.
+   * like those regarding circular dependencies or instability.
+   * Only the to.moreUnstable, to.circular, and path (both from and to)
+   * attributes work at the moment. Other attributes will follow suit in later
+   * releases (depending on demand).
    */
   scope?: RuleScopeType;
 }