dependency-cruiser 16.1.0 → 16.2.1

package/README.md

@@ -42,7 +42,7 @@ a `.dependency-cruiser.js` configuration file attuned to your project[^1][^2].
     `npx`.
 
 [^2]:
-    If you don't don't want to use `npx`, but instead `pnpx` (from the `pnpm`
+    If you don't want to use `npx`, but instead `pnpx` (from the `pnpm`
     package manager) or `yarn` - please refer to that tool's documentation.
     Particularly `pnpx` has semantics that differ from `npx` quite significantly
     and that you want to be aware of before using it. In the mean time: `npx`

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.1",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -16,15 +16,48 @@
     "validation",
     "spelunking"
   ],
-  "author": {
-    "name": "Sander Verweij",
-    "url": "https://sverweij.github.io"
-  },
+  "author": "Sander Verweij (https://sverweij.github.io)",
   "contributors": [
-    {
-      "name": "Klaus Meinhardt",
-      "url": "https://github.com/ajafff"
-    }
+    "Hirotaka Miyagi (https://mh4gf.dev)",
+    "TruongSinh Tran-Nguyen (https://truongsinh.pro)",
+    "Bastian Hess (https://github.com/bashess)",
+    "Álvaro Cuesta (https://github.com/alvaro-cuesta)",
+    "anna (https://github.com/annamooseity)",
+    "Radosław Kłos (https://klos.dev)",
+    "Joshua T (https://github.com/radiantly)",
+    "Ivan (https://github.com/Winner95)",
+    "Frieder Bluemle (https://github.com/friederbluemle)",
+    "davidparkagoda (https://github.com/davidparkagoda)",
+    "Matt Button (https://github.com/BRMatt)",
+    "Jon Lauridsen (https://jonlauridsen.com)",
+    "Klaus Meinhardt (https://github.com/ajafff)",
+    "cunzaizhuyi (https://github.com/cunzaizhuyi)",
+    "Greg Lockwood (https://github.com/greglockwood)",
+    "Jeremy Magland (https://github.com/magland)",
+    "Sebastian Landwehr (https://sebastianlandwehr.com)",
+    "Brody McKee (https://github.com/mrmckeb)",
+    "Bin (https://github.com/soulhat)",
+    "정건우 (https://www.zigae.com/)",
+    "Roy Swinkels (https://github.com/donroyco)",
+    "Martin Slota (https://github.com/martinslota)",
+    "Luke Page (https://github.com/lukeapage)",
+    "Emily Marigold Klassen (https://forivall.com)",
+    "Christian Vuerings (https://github.com/christianvuerings)",
+    "Yuanhai He (https://bestmike007.com)",
+    "Quentin de Metz (https://github.com/quentindemetz)",
+    "Lars Artmann (https://larsartmann.com)",
+    "Jessica Kerr (https://jessitron.com)",
+    "Creative Ataraxia (https://github.com/Creative-Ataraxia)",
+    "0xflotus (https://github.com/0xflotus)",
+    "Daniel Edholm Ignat (https://github.com/dignite)",
+    "Daniel Rodríguez Rivero (https://danielorodriguez.com)",
+    "Nick Ribal (https://github.com/elektronik2k5)",
+    "Richard Musiol https(://github.com/neelance)",
+    "Sharang Pai (https://sharangpai.me)",
+    "Stefan Gojan (https://stefan-gojan.de)",
+    "Tharun Rajendran (https://github.com/tharun208)",
+    "electrovir (https://github.com/electrovir)",
+    "fusheng (https://github.com/lin-hun)"
   ],
   "license": "MIT",
   "repository": {
@@ -106,20 +139,20 @@
     "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",
     "json5": "2.2.3",
     "lodash": "4.17.21",
-    "picomatch": "3.0.1",
+    "picomatch": "4.0.1",
     "prompts": "2.4.2",
     "rechoir": "^0.8.0",
     "safe-regex": "2.1.1",
-    "semver": "^7.5.4",
+    "semver": "^7.6.0",
     "semver-try-require": "6.2.3",
     "teamcity-service-messages": "0.1.14",
     "tsconfig-paths-webpack-plugin": "4.1.0",
@@ -127,11 +160,11 @@
     "wrap-ansi": "9.0.0"
   },
   "overrides": {
-    "semver": "^7.5.4",
+    "semver": "^7.6.0",
     "postcss": "^8.4.31"
   },
   "resolutions": {
-    "semver": "^7.5.4",
+    "semver": "^7.6.0",
     "postcss": "^8.4.31"
   },
   "engines": {

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

@@ -199,38 +199,31 @@ module.exports = {
   ],
   options: {
 
-    /* conditions specifying which files not to follow further when encountered:
-       - path: a regular expression to match
-       - dependencyTypes: see https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md#dependencytypes-and-dependencytypesnot
-       for a complete list
-    */
+    /* Which modules not to follow further when encountered */
     doNotFollow: {
-      path: 'node_modules'
+      /* path: an array of regular expressions in strings to match against */
+      path: ['node_modules']
     },
 
-    /* conditions specifying which dependencies to exclude
-       - path: a regular expression to match
-       - dynamic: a boolean indicating whether to ignore dynamic (true) or static (false) dependencies.
-          leave out if you want to exclude neither (recommended!)
-    */
+    /* Which modules to exclude */
     // exclude : {
+    //   /* path: an array of regular expressions in strings to match against */
     //   path: '',
-    //   dynamic: true
     // },
 
-    /* pattern specifying which files to include (regular expression)
+    /* Which modules to exclusively include (array of regular expressions in strings)
        dependency-cruiser will skip everything not matching this pattern
     */
-    // includeOnly : '',
+    // includeOnly : [''],
 
     /* dependency-cruiser will include modules matching against the focus
-       regular expression in its output, as well as their neighbours (direct
-       dependencies and dependents)
+       regular expression in its output, as well as their direct neighbours 
+       (dependencies and dependents)
     */
     // focus : '',
 
-    /* List of module systems to cruise. 
-       When left out dependency-cruiser will fall back to the list of _all_ 
+    /* List of module systems to cruise.
+       When left out dependency-cruiser will fall back to the list of _all_
        module systems it knows of. It's the default because it's the safe option
        It might come at a performance penalty, though.
        moduleSystems: ['amd', 'cjs', 'es6', 'tsd']
@@ -245,7 +238,7 @@ module.exports = {
        to open it on your online repo or \`vscode://file/$\{process.cwd()}/\` to 
        open it in visual studio code),
      */
-    // prefix: '',
+    // prefix: 'vscode://file/$\{process.cwd()}/\',
 
     /* false (the default): ignore dependencies that only exist before typescript-to-javascript compilation
        true: also detect dependencies that only exist before typescript-to-javascript compilation
@@ -253,10 +246,9 @@ module.exports = {
      */
     {{tsPreCompilationDepsAttribute}}
     
-    /* 
-       list of extensions to scan that aren't javascript or compile-to-javascript. 
+    /* list of extensions to scan that aren't javascript or compile-to-javascript.
        Empty by default. Only put extensions in here that you want to take into
-       account that are _not_ parsable. 
+       account that are _not_ parsable.
     */
     // extraExtensionsToScan: [".json", ".jpg", ".png", ".svg", ".webp"],
 
@@ -293,9 +285,7 @@ module.exports = {
 
     /* Babel config ('.babelrc', '.babelrc.json', '.babelrc.json5', ...) to use
       for compilation (and whatever other naughty things babel plugins do to
-      source code). This feature is well tested and usable, but might change
-      behavior a bit over time (e.g. more precise results for used module 
-      systems) without dependency-cruiser getting a major version bump.
+      source code).
      */
     {{babelConfigAttribute}}
 
@@ -305,57 +295,37 @@ module.exports = {
        a hack.
     */
     // exoticRequireStrings: [],
+    
     /* options to pass on to enhanced-resolve, the package dependency-cruiser
-       uses to resolve module references to disk. You can set most of these
-       options in a webpack.conf.js - this section is here for those
-       projects that don't have a separate webpack config file.
+       uses to resolve module references to disk. The values below should be
+       suitable for most situations
 
-       Note: settings in webpack.conf.js override the ones specified here.
+       If you use webpack: you can also set these in webpack.conf.js. The set
+       there will override the ones specified here.
      */
     enhancedResolveOptions: {
-      /* List of strings to consider as 'exports' fields in package.json. Use
-         ['exports'] when you use packages that use such a field and your environment
-         supports it (e.g. node ^12.19 || >=14.7 or recent versions of webpack).
-
-         If you have an \`exportsFields\` attribute in your webpack config, that one
-         will have precedence over the one specified here.
-      */ 
+      /* What to consider as an 'exports' field in package.jsons */ 
       exportsFields: ["exports"],
-      /* List of conditions to check for in the exports field. e.g. use ['imports']
-         if you're only interested in exposed es6 modules, ['require'] for commonjs,
-         or all conditions at once \`(['import', 'require', 'node', 'default']\`)
-         if anything goes for you. Only works when the 'exportsFields' array is
-         non-empty.
-
-        If you have a 'conditionNames' attribute in your webpack config, that one will
-        have precedence over the one specified here.
+      /* List of conditions to check for in the exports field.
+         Only works when the 'exportsFields' array is non-empty.
       */
       conditionNames: ["import", "require", "node", "default", "types"],
       /*
          The extensions, by default are the same as the ones dependency-cruiser
          can access (run \`npx depcruise --info\` to see which ones that are in
-         _your_ environment. If that list is larger than what you need (e.g. 
-         it contains .js, .jsx, .ts, .tsx, .cts, .mts - but you don't use 
-         TypeScript you can pass just the extensions you actually use (e.g. 
-         [".js", ".jsx"]). This can speed up the most expensive step in 
-         dependency cruising (module resolution) quite a bit.
+         _your_ environment. If that list is larger than you need you can pass
+         the extensions you actually use (e.g. [".js", ".jsx"]). This can speed
+         up the most expensive step in dependency cruising (module resolution)
+          quite a bit.
        */
       {{extensionsAttribute}}
-      /* 
-         If your TypeScript project makes use of types specified in 'types'
-         fields in package.jsons of external dependencies, specify "types"
-         in addition to "main" in here, so enhanced-resolve (the resolver
-         dependency-cruiser uses) knows to also look there. You can also do
-         this if you're not sure, but still use TypeScript. In a future version
-         of dependency-cruiser this will likely become the default.
-       */
+      /* What to consider a 'main' field in package.json */
       {{mainFieldsAttribute}}
       /*
-         A list of alias fields in manifests (package.jsons).
-         Specify a field, such as browser, to be parsed according to
-         [this specification](https://github.com/defunctzombie/package-browser-field-spec).
-         Also see [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealiasfields)
-         in the webpack docs. 
+         A list of alias fields in package.jsons
+         See [this specification](https://github.com/defunctzombie/package-browser-field-spec) and
+         the [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealiasfields)
+         documentation in the webpack docs. 
          
          Defaults to an empty array (don't use any alias fields).
        */
@@ -377,70 +347,13 @@ module.exports = {
         */
         // theme: {
         //   graph: {
-        //     /* use splines: "ortho" for straight lines. Be aware though
-        //       graphviz might take a long time calculating ortho(gonal)
-        //       routings.
+        //     /* splines: "ortho" will give you straight lines at the expense of
+        //                 being slow to render on big graphs
+        //        splines: "true" will give you bezier curves which are faster
+        //                 but might not look as nice
         //    */
         //     splines: "true"
         //   },
-        //   modules: [
-        //     {
-        //       criteria: { matchesFocus: true },
-        //       attributes: {
-        //         fillcolor: "lime",
-        //         penwidth: 2,
-        //       },
-        //     },
-        //     {
-        //       criteria: { matchesFocus: false },
-        //       attributes: {
-        //         fillcolor: "lightgrey",
-        //       },
-        //     },
-        //     {
-        //       criteria: { matchesReaches: true },
-        //       attributes: {
-        //         fillcolor: "lime",
-        //         penwidth: 2,
-        //       },
-        //     },
-        //     {
-        //       criteria: { matchesReaches: false },
-        //       attributes: {
-        //         fillcolor: "lightgrey",
-        //       },
-        //     },
-        //     {
-        //       criteria: { source: "^src/model" },
-        //       attributes: { fillcolor: "#ccccff" }
-        //     },
-        //     {
-        //       criteria: { source: "^src/view" },
-        //       attributes: { fillcolor: "#ccffcc" }
-        //     },
-        //   ],
-        //   dependencies: [
-        //     {
-        //       criteria: { "rules[0].severity": "error" },
-        //       attributes: { fontcolor: "red", color: "red" }
-        //     },
-        //     {
-        //       criteria: { "rules[0].severity": "warn" },
-        //       attributes: { fontcolor: "orange", color: "orange" }
-        //     },
-        //     {
-        //       criteria: { "rules[0].severity": "info" },
-        //       attributes: { fontcolor: "blue", color: "blue" }
-        //     },
-        //     {
-        //       criteria: { resolved: "^src/model" },
-        //       attributes: { color: "#0000ff77" }
-        //     },
-        //     {
-        //       criteria: { resolved: "^src/view" },
-        //       attributes: { color: "#00770077" }
-        //     }
-        //   ]
         // }
       },
       archi: {
@@ -455,7 +368,7 @@ module.exports = {
            https://github.com/sverweij/dependency-cruiser/blob/main/doc/options-reference.md#reporteroptions
            for details and some examples. If you don't specify a theme
            for 'archi' dependency-cruiser will use the one specified in the
-           dot section (see above), if any, and otherwise use the default one.
+           dot section above and otherwise use the default one.
          */
         // theme: {
         // },

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/init-config/write-run-scripts-to-manifest.mjs

@@ -102,7 +102,7 @@ export function addRunScriptsToManifest(pManifest, pAdditionalRunScripts) {
   const lManifest = { ...(pManifest || {}) };
   const lExistingRunScripts = lManifest.scripts || {};
 
-  // This could instead simply be done with
+  // This could instead be done with
   // {...pAdditionalScriptEntries, ...lManifest} and no logic at all,
   // but that'd add the new scripts on top, which doesn't feel right
   //

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/config-utl/extract-depcruise-config/index.mjs

@@ -37,8 +37,9 @@ async function processExtends(pReturnValue, pAlreadyVisited, pBaseDirectory) {
  * Reads the file with name `pConfigFileName` returns the parsed cruise
  * options.
  *
- * You can safely ignore the optional parameters. Simply this should work (given
- * `.dependency-cruiser.js` exists and contains a valid dependency-cruiser config)
+ * You can safely ignore the optional parameters. This should work (given
+ * `.dependency-cruiser.js` exists and contains a valid dependency-cruiser
+ * config)
  *
  * ```javascript
  * const depcruiseConfig = extractDepcruiseConfig("./.dependency-cruiser.js")

package/src/extract/resolve/module-classifiers.mjs

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines */
 import { isAbsolute, resolve as path_resolve } from "node:path";
 import { join as posix_join } from "node:path/posix";
-import { isMatch } from "picomatch";
+import picomatch from "picomatch";
 import getExtension from "#utl/get-extension.mjs";
 
 let gFollowableExtensionsCache = new Set();
@@ -158,7 +158,7 @@ function isWorkspaceAliased(pModuleName, pResolvedModuleName, pManifest) {
       (pWorkspace) =>
         pWorkspace.endsWith("/") ? `${pWorkspace}**` : `${pWorkspace}/**`,
     );
-    if (isMatch(pResolvedModuleName, lModuleFriendlyWorkspaceGlobs)) {
+    if (picomatch.isMatch(pResolvedModuleName, lModuleFriendlyWorkspaceGlobs)) {
       return true;
     }
     // it's possible to run node with --preserve-symlinks, in which case
@@ -176,7 +176,10 @@ function isWorkspaceAliased(pModuleName, pResolvedModuleName, pManifest) {
       lModuleFriendlyWorkspaceGlobs.map(
         (pWorkspace) => `(node_modules/)?${pWorkspace}`,
       );
-    return isMatch(pModuleName, lModuleFriendlyWorkspaceGlobsWithNodeModules);
+    return picomatch.isMatch(
+      pModuleName,
+      lModuleFriendlyWorkspaceGlobsWithNodeModules,
+    );
   }
   return false;
 }

package/src/meta.js

@@ -1,7 +1,7 @@
 /* generated - don't edit */
 
 module.exports = {
-  version: "16.1.0",
+  version: "16.2.1",
   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/config-utl/extract-depcruise-config.d.mts

@@ -4,8 +4,9 @@ import type { ICruiseOptions } from "../options.mjs";
  * Reads the file with name `pConfigFileName` returns the parsed cruise
  * options.
  *
- * You can safely ignore the optional parameters. Simply this should work (given
- * `.dependency-cruiser.js` exists and contains a valid dependency-cruiser config)
+ * You can safely ignore the optional parameters. This should work (given
+ * `.dependency-cruiser.js` exists and contains a valid dependency-cruiser
+ * config)
  *
  * ```javascript
  * const depcruiseConfig = extractDepcruiseConfig("./.dependency-cruiser.js")

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;
 }