npm - dependency-cruiser - Versions diffs - 15.4.0 → 15.5.0 - Mend

dependency-cruiser 15.4.0 → 15.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/configs/plugins/3d-reporter-plugin.mjs ADDED Viewed

@@ -0,0 +1,127 @@
+import * as path from "node:path";
+import figures from "figures";
+const TEMPLATE = `
+<html>
+<head>
+  <style> body { margin: 0; } </style>
+  <script type="text/javascript" src="https://unpkg.com/three"></script>
+  <script type="text/javascript" src="https://unpkg.com/three-spritetext"></script>
+  <script type="text/javascript" src="https://unpkg.com/3d-force-graph"></script>
+</head>
+<body>
+  <div id="3d-graph"></div>
+  <script>
+    const gData = {
+      nodes: @@NODES@@,
+      links: @@LINKS@@
+    };
+    const elem = document.getElementById('3d-graph')
+    const Graph = ForceGraph3D()
+      (elem)
+        .graphData(gData)
+        .nodeAutoColorBy('group')
+        .nodeLabel(node => node.label)
+        .onNodeHover(node => elem.style.cursor = node ? 'pointer' : null)
+        .onNodeClick(node => {
+          // Aim at node from outside it
+          const distance = 40;
+          const distRatio = 1 + distance/Math.hypot(node.x, node.y, node.z);
+          Graph.cameraPosition(
+            { x: node.x * distRatio, y: node.y * distRatio, z: node.z * distRatio }, // new position
+            node, // lookAt ({ x, y, z })
+            3000  // ms transition duration
+          )
+        })
+        /* nice idea, but the 3D graph tends to look cluttered. Also GPU/ CPU
+           intensive when run on a serious code base (e.g. react that has
+            ~4500 nodes and ~10000 links
+        */
+        .nodeThreeObject(node => {
+          const sprite = new SpriteText(node.displayname);
+          sprite.material.depthWrite = true; // make sprite background transparent
+          sprite.color = node.color;
+          sprite.textHeight = 6;
+          return sprite;
+        })
+        .linkOpacity(0.2)
+        .linkWidth(2)
+        .linkDirectionalArrowLength(4)
+        .linkDirectionalParticles(7) // cool but a bit GPU intensive
+        .linkLabel(link => link.label)
+        .onLinkHover(link => elem.style.cursor = link ? 'pointer' : null)
+  </script>
+</body>
+</html>`;
+function deriveGroup(pFileName) {
+  let lReturnValue = "unknown";
+  const lGroupPositionInRe = 2;
+  const lMatch = path.dirname(pFileName).match(/^([^/]+)\/([^/]+)/);
+  if (lMatch) {
+    // eslint-disable-next-line security/detect-object-injection
+    lReturnValue = lMatch[lGroupPositionInRe];
+  }
+  return lReturnValue;
+}
+function formatFileName(pFileName) {
+  return `${path.dirname(pFileName)}/<b>${path.basename(pFileName)}</b>`;
+}
+function formatDependency(pFrom, pTo) {
+  return `${formatFileName(pFrom)} ${figures.arrowRight}</br>${formatFileName(
+    pTo
+  )}`;
+}
+/**
+ *
+ * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult
+ */
+function render3DThing(pCruiseResult) {
+  const lNodes = pCruiseResult.modules.map((pModule) => {
+    return {
+      id: pModule.source,
+      displayname: path.basename(pModule.source),
+      dirname: path.dirname(pModule.source),
+      label: formatFileName(pModule.source),
+      group: deriveGroup(pModule.source),
+    };
+  });
+  const lLinks = pCruiseResult.modules.reduce(
+    (pAll, pCurrentModule) =>
+      pAll.concat(
+        pCurrentModule.dependencies.map((pDependency) => ({
+          source: pCurrentModule.source,
+          target: pDependency.resolved,
+          label: formatDependency(pCurrentModule.source, pDependency.resolved),
+        }))
+      ),
+    []
+  );
+  return TEMPLATE.replace(/@@NODES@@/g, JSON.stringify(lNodes)).replace(
+    /@@LINKS@@/g,
+    JSON.stringify(lLinks)
+  );
+}
+/**
+ * Sample plugin: 3d representation
+ *
+ * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult -
+ *      the output of a dependency-cruise adhering to dependency-cruiser's
+ *      cruise result schema
+ * @return {import('../../types/dependency-cruiser').IReporterOutput} -
+ *      output: a string
+ *      exitCode: 0
+ */
+export default (pCruiseResult) => ({
+  output: render3DThing(pCruiseResult),
+  exitCode: 0,
+});

package/configs/plugins/stats-reporter-plugin.mjs ADDED Viewed

@@ -0,0 +1,82 @@
+const MEDIAN = 0.5;
+const P75 = 0.75;
+const DEFAULT_JSON_INDENT = 2;
+function doMagic(pCruiseResult) {
+  let lReturnValue = {};
+  if (pCruiseResult.modules.some((pModule) => pModule.dependents)) {
+    const lDependentCounts = pCruiseResult.modules
+      .map((pModule) => pModule.dependents.length)
+      .sort();
+    lReturnValue = {
+      minDependentsPerModule: lDependentCounts[0] || 0,
+      maxDependentsPerModule:
+        lDependentCounts[Math.max(lDependentCounts.length - 1, 0)] || 0,
+      meanDependentsPerModule:
+        lDependentCounts.reduce((pAll, pCurrent) => pAll + pCurrent, 0) /
+        pCruiseResult.summary.totalCruised,
+      medianDependentsPerModule:
+        lDependentCounts[
+          Math.max(0, Math.floor(lDependentCounts.length * MEDIAN))
+        ],
+      p75DependentsPerModule:
+        lDependentCounts[
+          Math.max(0, Math.floor(lDependentCounts.length * P75))
+        ],
+    };
+  }
+  return lReturnValue;
+}
+/**
+ * returns an object with some stats from the ICruiseResult pCruiseResult it
+ * got passed
+ *
+ * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult - a result from a cruise.
+ * @return {string} an object with some stats
+ */
+function samplePluginReporter(pCruiseResult) {
+  const lDependencyCounts = pCruiseResult.modules
+    .map((pModule) => pModule.dependencies.length)
+    .sort();
+  return {
+    moduleCount: pCruiseResult.summary.totalCruised,
+    dependencyCount: pCruiseResult.summary.totalDependenciesCruised,
+    minDependenciesPerModule: lDependencyCounts[0] || 0,
+    maxDependenciesPerModule:
+      lDependencyCounts[Math.max(lDependencyCounts.length - 1, 0)] || 0,
+    meanDependenciesPerModule:
+      pCruiseResult.summary.totalDependenciesCruised /
+      pCruiseResult.summary.totalCruised,
+    medianDependenciesPerModule:
+      lDependencyCounts[
+        Math.max(0, Math.floor(lDependencyCounts.length * MEDIAN))
+      ],
+    p75DependenciesPerModule:
+      lDependencyCounts[
+        Math.max(0, Math.floor(lDependencyCounts.length * P75))
+      ],
+    ...doMagic(pCruiseResult),
+  };
+}
+/**
+ * Sample plugin
+ *
+ * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult -
+ *      the output of a dependency-cruise adhering to dependency-cruiser's
+ *      cruise result schema
+ * @return {import('../../types/dependency-cruiser').IReporterOutput} -
+ *      output: some stats on modules and dependencies in json format
+ *      exitCode: 0
+ */
+export default (pCruiseResult) => ({
+  output: JSON.stringify(
+    samplePluginReporter(pCruiseResult),
+    null,
+    DEFAULT_JSON_INDENT
+  ),
+  exitCode: 0,
+});

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "15.4.0",
+  "version": "15.5.0",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -51,39 +51,49 @@
   },
   "exports": {
     ".": {
-      "import": "./src/main/index.mjs",
-      "types": "./types/dependency-cruiser.d.ts"
+      "types": "./types/dependency-cruiser.d.mts",
+      "import": "./src/main/index.mjs"
     },
     "./config-utl/extract-babel-config": {
-      "import": "./src/config-utl/extract-babel-config.mjs",
-      "types": "./types/extract-babel-config.d.ts"
+      "types": "./types/config-utl/extract-babel-config.d.mts",
+      "import": "./src/config-utl/extract-babel-config.mjs"
     },
     "./config-utl/extract-depcruise-config": {
-      "import": "./src/config-utl/extract-depcruise-config/index.mjs",
-      "types": "./types/extract-depcruise-config.d.ts"
+      "types": "./types/config-utl/extract-depcruise-config.d.mts",
+      "import": "./src/config-utl/extract-depcruise-config/index.mjs"
     },
     "./config-utl/extract-ts-config": {
-      "import": "./src/config-utl/extract-ts-config.mjs",
-      "types": "./types/extract-ts-config.d.ts"
+      "types": "./types/config-utl/extract-ts-config.d.mts",
+      "import": "./src/config-utl/extract-ts-config.mjs"
     },
     "./config-utl/extract-webpack-resolve-config": {
-      "import": "./src/config-utl/extract-webpack-resolve-config.mjs",
-      "types": "./types/extract-webpack-resolve-config.d.ts"
+      "types": "./types/config-utl/extract-webpack-resolve-config.d.mts",
+      "import": "./src/config-utl/extract-webpack-resolve-config.mjs"
     },
-    "./sample-reporter-plugin": "./configs/plugins/stats-reporter-plugin.mjs",
-    "./sample-3d-reporter-plugin": "./configs/plugins/3d-reporter-plugin.mjs",
-    "./mermaid-reporter-plugin": "./src/report/mermaid.mjs"
+    "./sample-reporter-plugin": {
+      "types": "./types/plugins/stats-reporter-plugin.d.mts",
+      "import": "./configs/plugins/stats-reporter-plugin.mjs"
+    },
+    "./sample-3d-reporter-plugin": {
+      "types": "./types/plugins/3d-reporter-plugin.d.mts",
+      "import": "./configs/plugins/3d-reporter-plugin.mjs"
+    },
+    "./mermaid-reporter-plugin": {
+      "types": "./types/plugins/mermaid-reporter-plugin.d.mts",
+      "import": "./src/report/mermaid.mjs"
+    }
   },
-  "types": "types/dependency-cruiser.d.ts",
+  "types": "types/dependency-cruiser.d.mts",
   "files": [
     "bin",
     "configs/**/*.js",
+    "configs/plugins/",
     "src",
     "!src/**/*.json",
     "!src/**/*.hbs",
     "!src/**/*.md",
     "!**/*.DS_Store",
-    "types/*.d.ts",
+    "types/**/*.d.mts",
     "LICENSE",
     "package.json",
     "README.md"
@@ -103,7 +113,7 @@
     "depcruise:graph:doc:fmt-archi": "./bin/depcruise-fmt.mjs -T archi -f - node_modules/.cache/tmp_graph_deps.json | dot -T svg -Gordering=in -Grankdir=TD | tee doc/real-world-samples/dependency-cruiser-archi-graph.svg | node bin/wrap-stream-in-html.mjs > docs/dependency-cruiser-archi-graph.html",
     "depcruise:graph:doc:fmt-dir": "./bin/depcruise-fmt.mjs -T ddot -f - node_modules/.cache/tmp_graph_deps.json | dot -T svg -Grankdir=TD | tee doc/real-world-samples/dependency-cruiser-dir-graph.svg | node bin/wrap-stream-in-html.mjs > docs/dependency-cruiser-dir-graph.html",
     "depcruise:graph:doc:fmt-schema": "cd tools/schema && node ../../bin/dependency-cruise.mjs . --output-type dot | dot -T svg | tee ../overview.svg | node ../../bin/wrap-stream-in-html.mjs > ../../docs/schema-overview.html && cd -",
-    "depcruise:graph:doc:fmt-types": "cd types && node ../bin/dependency-cruise.mjs . --output-type dot | dot -T svg > overview.svg && cd -",
+    "depcruise:graph:doc:fmt-types": "cd types && node ../bin/dependency-cruise.mjs . --output-type dot | dot -T svg | tee overview.svg | ../bin/wrap-stream-in-html.mjs > overview.html && cd -",
     "depcruise:graph:doc:samples": "sh tools/generate-samples.sh",
     "depcruise:graph:mermaid": "node ./bin/dependency-cruise.mjs bin src --include-only ^src/ --collapse 2 --output-type mermaid",
     "depcruise:graph:mermaid:diff": "node ./bin/dependency-cruise.mjs bin src test types tools --config configs/.dependency-cruiser-unlimited.mjs --output-type mermaid --reaches \"$(watskeburt $SHA)\"",
@@ -113,8 +123,8 @@
     "depcruise:report:view": "node ./bin/dependency-cruise.mjs src bin test configs types --output-type err-html --config configs/.dependency-cruiser-show-metrics-config.mjs --output-to - | browser",
     "depcruise:focus": "node ./bin/dependency-cruise.mjs src bin test configs types tools --progress --no-cache --output-type text --focus",
     "depcruise:reaches": "node ./bin/dependency-cruise.mjs src bin test configs types tools --progress --no-cache --config configs/.dependency-cruiser-unlimited.mjs --output-type text --reaches",
-    "format": "prettier --log-level warn --write \"src/**/*.js\" \"configs/**/*.js\" \"tools/**/*.mjs\" \"bin/*\" \"types/*.d.ts\" \"test/**/*.spec.{cjs,js}\" \"test/**/*.{spec,utl}.mjs\"",
-    "format:check": "prettier --log-level warn --check \"src/**/*.js\" \"configs/**/*.js\" \"tools/**/*.mjs\" \"bin/*\" \"types/*.d.ts\" \"test/**/*.spec.{cjs,js}\" \"test/**/*.{spec,utl}.mjs\"",
+    "format": "prettier --log-level warn --write \"src/**/*.js\" \"configs/**/*.js\" \"tools/**/*.mjs\" \"bin/*\" \"types/*.d.mts\" \"test/**/*.spec.{cjs,js}\" \"test/**/*.{spec,utl}.mjs\"",
+    "format:check": "prettier --log-level warn --check \"src/**/*.js\" \"configs/**/*.js\" \"tools/**/*.mjs\" \"bin/*\" \"types/*.d.mts\" \"test/**/*.spec.{cjs,js}\" \"test/**/*.{spec,utl}.mjs\"",
     "lint": "npm-run-all --parallel --aggregate-output lint:eslint format:check lint:types",
     "lint:eslint": "eslint bin/dependency-cruise.mjs bin src test configs tools/**/*.mjs --cache --cache-location node_modules/.cache/eslint/",
     "lint:eslint:fix": "eslint --fix bin src test configs tools/**/*.mjs --cache --cache-location node_modules/.cache/eslint/",
@@ -122,8 +132,8 @@
     "lint:fix": "npm-run-all lint:eslint:fix format lint:types:fix",
     "lint:types": "npm-run-all lint:types:tsc lint:types:lint",
     "lint:types:tsc": "tsc --project types/tsconfig.json",
-    "lint:types:lint": "eslint --no-ignore --config types/.eslintrc.json types/*.d.ts",
-    "lint:types:fix": "eslint --no-ignore --config types/.eslintrc.json --fix types/*.d.ts",
+    "lint:types:lint": "eslint --no-ignore --config types/.eslintrc.json types/*.d.mts",
+    "lint:types:fix": "eslint --no-ignore --config types/.eslintrc.json --fix types/*.d.mts",
     "prepare": "husky install",
     "scm:push": "run-p --aggregate-output scm:push:*",
     "scm:push:bitbucket-mirror": "run-p --aggregate-output scm:push:bitbucket-mirror:*",
@@ -186,11 +196,11 @@
     "@babel/preset-typescript": "7.23.3",
     "@swc/core": "1.3.99",
     "@types/lodash": "4.14.202",
-    "@types/node": "20.9.3",
+    "@types/node": "20.10.0",
     "@types/prompts": "2.4.9",
     "@typescript-eslint/eslint-plugin": "6.12.0",
     "@typescript-eslint/parser": "6.12.0",
-    "@vue/compiler-sfc": "3.3.8",
+    "@vue/compiler-sfc": "3.3.9",
     "c8": "8.0.1",
     "coffeescript": "2.7.0",
     "eslint": "8.54.0",

package/src/cache/metadata-strategy.mjs CHANGED Viewed

@@ -15,7 +15,7 @@ import { bus } from "#utl/bus.mjs";
 export default class MetaDataStrategy {
   /**
    * @param {string} _pDirectory
-   * @param {import("../../types/cruise-result.js").ICruiseResult} _pCachedCruiseResult
+   * @param {import("../../types/cruise-result.mjs").ICruiseResult} _pCachedCruiseResult
    * @param {Object} pOptions
    * @param {Set<string>} pOptions.extensions
    * @param {Set<import("watskeburt").changeTypeType>=} pOptions.interestingChangeTypes

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

@@ -154,7 +154,15 @@ module.exports = {
       },
       to: {
         dependencyTypes: [
-          'npm-dev'
+          'npm-dev',
+        ],
+        // type only dependencies are not a problem as they don't end up in the
+        // production code or are ignored by the runtime.
+        dependencyTypesNot: [
+          'type-only'
+        ],
+        pathNot: [
+          'node_modules/@types/'
         ]
       }
     },

package/src/cli/tools/svg-in-html-snippets/{script.snippet.js → script.js} RENAMED Viewed

@@ -10,7 +10,7 @@ var title2ElementMap = (function makeElementMap() {
 function getHoverHandler(pTitle2ElementMap) {
   /** @type {string} */
-  var currentHighlightedTitle;
+  var currentHighlightedTitle = "";
   /** @param {MouseEvent} pMouseEvent */
   return function hoverHighlightHandler(pMouseEvent) {
@@ -31,7 +31,7 @@ function getHoverHandler(pTitle2ElementMap) {
 function getSelectHandler(pTitle2ElementMap) {
   /** @type {string} */
-  var currentHighlightedTitle;
+  var currentHighlightedTitle = "";
   /** @param {MouseEvent} pMouseEvent */
   return function selectHighlightHandler(pMouseEvent) {
@@ -64,6 +64,9 @@ function Mode() {
     this._mode = SELECT;
   }
+  /**
+   * @returns {number}
+   */
   function get() {
     return this._mode || HOVER;
   }
@@ -210,23 +213,23 @@ function addHighlight(pGroup) {
   }
 }
-var hints = {
+var gHints = {
   HIDDEN: 1,
   SHOWN: 2,
   state: this.HIDDEN,
   show: function () {
     document.getElementById("hints").removeAttribute("style");
-    hints.state = hints.SHOWN;
+    gHints.state = gHints.SHOWN;
   },
   hide: function () {
     document.getElementById("hints").style = "display:none";
-    hints.state = hints.HIDDEN;
+    gHints.state = gHints.HIDDEN;
   },
   toggle: function () {
-    if ((hints.state || hints.HIDDEN) === hints.HIDDEN) {
-      hints.show();
+    if ((gHints.state || gHints.HIDDEN) === gHints.HIDDEN) {
+      gHints.show();
     } else {
-      hints.hide();
+      gHints.hide();
     }
   },
 };
@@ -236,16 +239,48 @@ function keyboardEventHandler(pKeyboardEvent) {
   if (pKeyboardEvent.key === "Escape") {
     resetNodesAndEdges();
     gMode.setToHover();
-    hints.hide();
+    gHints.hide();
   }
   if (pKeyboardEvent.key === "F1") {
     pKeyboardEvent.preventDefault();
-    hints.toggle();
+    gHints.toggle();
   }
 }
 document.addEventListener("contextmenu", getSelectHandler(title2ElementMap));
 document.addEventListener("mouseover", getHoverHandler(title2ElementMap));
 document.addEventListener("keydown", keyboardEventHandler);
-document.getElementById("close-hints").addEventListener("click", hints.hide);
-document.getElementById("button_help").addEventListener("click", hints.toggle);
+document.getElementById("close-hints").addEventListener("click", gHints.hide);
+document.getElementById("button_help").addEventListener("click", gHints.toggle);
+document.querySelector("svg").insertAdjacentHTML(
+  "afterbegin",
+  `<linearGradient id="edgeGradient">
+      <stop offset="0%" stop-color="fuchsia"/>
+      <stop offset="100%" stop-color="purple"/>
+   </linearGradient>
+  `,
+);
+// Add a small increment to the last value of the path to make gradients on
+// horizontal paths work. Without them all browsers I tested with (firefox,
+// chrome) do not render the gradient, but instead make the line transparent
+// (or the color of the background, I haven't looked into it that deeply,
+// but for the hack it doesn't matter which).
+function skewLineABit(lDrawingInstructions) {
+  var lLastValue = lDrawingInstructions.match(/(\d+\.?\d*)$/)[0];
+  // Smaller values than .001 _should_ work as well, but don't in all
+  // cases. Even this value is so small that it is not visible to the
+  // human eye (tested with the two I have at my disposal).
+  var lIncrement = 0.001;
+  var lNewLastValue = parseFloat(lLastValue) + lIncrement;
+  return lDrawingInstructions.replace(lLastValue, lNewLastValue);
+}
+nodeListToArray(document.querySelectorAll("path"))
+  .filter(function (pElement) {
+    return pElement.parentElement.classList.contains("edge");
+  })
+  .forEach(function (pElement) {
+    pElement.attributes.d.value = skewLineABit(pElement.attributes.d.value);
+  });

package/src/cli/tools/svg-in-html-snippets/style.css ADDED Viewed

@@ -0,0 +1,101 @@
+.node:active path,
+.node:hover path,
+.node.current path,
+.node:active polygon,
+.node:hover polygon,
+.node.current polygon {
+  stroke: fuchsia;
+  stroke-width: 2;
+}
+.edge:active path,
+.edge:hover path,
+.edge.current path,
+.edge:active ellipse,
+.edge:hover ellipse,
+.edge.current ellipse {
+  stroke: url(#edgeGradient);
+  stroke-width: 3;
+  stroke-opacity: 1;
+}
+.edge:active polygon,
+.edge:hover polygon,
+.edge.current polygon {
+  stroke: fuchsia;
+  stroke-width: 3;
+  fill: fuchsia;
+  stroke-opacity: 1;
+  fill-opacity: 1;
+}
+.edge:active text,
+.edge:hover text {
+  fill: fuchsia;
+}
+.cluster path {
+  stroke-width: 3;
+}
+.cluster:active path,
+.cluster:hover path {
+  fill: #ffff0011;
+}
+div.hint {
+  background-color: #000000aa;
+  color: white;
+  font-family: Arial, Helvetica, sans-serif;
+  border-radius: 1rem;
+  position: fixed;
+  top: calc(50% - 4em);
+  right: calc(50% - 10em);
+  border: none;
+  padding: 1em 3em 1em 1em;
+}
+.hint button {
+  position: absolute;
+  font-weight: bolder;
+  right: 0.6em;
+  top: 0.6em;
+  color: inherit;
+  background-color: inherit;
+  border: 1px solid currentColor;
+  border-radius: 1em;
+  margin-left: 0.6em;
+}
+.hint a {
+  color: inherit;
+}
+#button_help {
+  color: white;
+  background-color: #00000011;
+  border-radius: 1em;
+  position: fixed;
+  top: 1em;
+  right: 1em;
+  font-size: 24pt;
+  font-weight: bolder;
+  width: 2em;
+  height: 2em;
+  border: none;
+}
+#button_help:hover {
+  cursor: pointer;
+  background-color: #00000077;
+}
+@media print {
+  #button_help {
+    display: none;
+  }
+  div.hint {
+    display: none;
+  }
+}

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

@@ -1,19 +1,56 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
-const HEADER_FILE = fileURLToPath(
-  new URL("svg-in-html-snippets/header.snippet.html", import.meta.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.snippet.js", import.meta.url)
-);
-const FOOTER_FILE = fileURLToPath(
-  new URL("svg-in-html-snippets/footer.snippet.html", import.meta.url)
+  new URL("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 file and returns it as a string.
+ * of the header and the footer and returns it as a string.
  *
  * Almost exactly the same as:
  * ```sh
@@ -26,18 +63,15 @@ const FOOTER_FILE = fileURLToPath(
  * @param {writeStream} pOutStream stream to write to
  */
 export default async function wrap(pInStream, pOutStream) {
-  const [lHeader, lScript, lEnd] = await Promise.all([
-    readFile(HEADER_FILE, "utf8"),
+  const [lStylesheet, lScript] = await Promise.all([
+    readFile(STYLESHEET_FILE, "utf8"),
     readFile(SCRIPT_FILE, "utf8"),
-    readFile(FOOTER_FILE, "utf8"),
   ]);
-  const lFooter = `<script>${lScript}</script>${lEnd}`;
-  pOutStream.write(lHeader);
+  pOutStream.write(getHeader(lStylesheet));
   pInStream
     .on("end", () => {
-      pOutStream.write(lFooter);
+      pOutStream.write(getFooter(lScript));
       pOutStream.end();
     })
     .on(
@@ -45,9 +79,17 @@ export default async function wrap(pInStream, pOutStream) {
       /* c8 ignore start */
       (pError) => {
         process.stderr.write(`${pError}\n`);
-      }
+      },
       /* c8 ignore stop */
     )
+    /*
+     * We could have put the whole html in a template literal, but we don't know
+     * how large the svg that's going to be injected is going to be - it could just
+     * as well be as large that if we're going to buffer it, it's going into out
+     * of memory territory.
+     *
+     * We circumvent that by streaming the svg in between the header and the footer.
+     */
     .on("data", (pChunk) => {
       pOutStream.write(pChunk);
     });