refactor: introduces use of node imports aliasses in package.json

.eslintrc.js

@@ -11,11 +11,14 @@ module.exports = {
     "@typescript-eslint/no-var-requires": "off", // we kind-of live off of those in here
     "@typescript-eslint/no-unused-vars": "off", // duplicate of the same in several other sets
     "budapestian/global-constant-pattern": "off", // currently does not work with the AST as emitted @typescript-eslint parser (FIXME)
-    "no-param-reassign": "error",
     "security/detect-non-literal-fs-filename": "off",
-    "unicorn/no-useless-fallback-in-spread": "off", // useful, probably. We'll try it later, though
     "import/exports-last": "off", // Useless remnant of the time when single pass compilers were in vogue
+    "import/no-unresolved": "off", // Does not recognize package.json #imports, which we use (in nodejs since v12.9.0), nor does it understand self-references to exports (e.g. dependency-cruiser/mermaid-reporter-plugin)
+    "no-param-reassign": "error",
+    "node/no-missing-import": "off", // Does not recognize package.json #imports, which we use (in nodejs since v12.9.0), nor does it understand self-references to exports (e.g. dependency-cruiser/mermaid-reporter-plugin)
+    "node/no-missing-require": "off", // Does not recognize package.json #imports, which we use (in nodejs since v12.9.0), nor does it understand self-references to exports (e.g. dependency-cruiser/mermaid-reporter-plugin)
     "unicorn/no-empty-file": "off", // See https://github.com/sindresorhus/eslint-plugin-unicorn/issues/2175
+    "unicorn/no-useless-fallback-in-spread": "off", // useful, probably. We'll try it later, though
   },
   overrides: [
     {

bin/depcruise-baseline.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { program } from "commander";
-import assertNodeEnvironmentSuitable from "../src/cli/assert-node-environment-suitable.mjs";
-import meta from "../src/meta.js";
-import cli from "../src/cli/index.mjs";
+import assertNodeEnvironmentSuitable from "#cli/assert-node-environment-suitable.mjs";
+import cli from "#cli/index.mjs";
+import meta from "#meta";
 
 function formatError(pError) {
   process.stderr.write(pError.message);

bin/depcruise-fmt.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { program } from "commander";
-import assertNodeEnvironmentSuitable from "../src/cli/assert-node-environment-suitable.mjs";
-import meta from "../src/meta.js";
-import format from "../src/cli/format.mjs";
+import assertNodeEnvironmentSuitable from "#cli/assert-node-environment-suitable.mjs";
+import format from "#cli/format.mjs";
+import meta from "#meta";
 
 function formatError(pError) {
   process.stderr.write(pError.message);

bin/dependency-cruise.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { EOL } from "node:os";
 import { program } from "commander";
-import assertNodeEnvironmentSuitable from "../src/cli/assert-node-environment-suitable.mjs";
-import meta from "../src/meta.js";
-import cli from "../src/cli/index.mjs";
+import assertNodeEnvironmentSuitable from "#cli/assert-node-environment-suitable.mjs";
+import cli from "#cli/index.mjs";
+import meta from "#meta";
 
 try {
   assertNodeEnvironmentSuitable();

bin/wrap-stream-in-html.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 
-import wrapStreamInHtml from "../src/cli/tools/wrap-stream-in-html.mjs";
+import wrapStreamInHtml from "#cli/tools/wrap-stream-in-html.mjs";
 
 wrapStreamInHtml(process.stdin, process.stdout);

package.json

@@ -44,6 +44,21 @@
     "depcruise-wrap-stream-in-html": "bin/wrap-stream-in-html.mjs"
   },
   "main": "src/main/index.mjs",
+  "imports": {
+    "#cache/*": "./src/cache/*",
+    "#config-utl/*": "./src/config-utl/*",
+    "#configuration-schema": "./src/schema/configuration.schema.mjs",
+    "#cli/*": "./src/cli/*",
+    "#cruise-result-schema": "./src/schema/cruise-result.schema.mjs",
+    "#enrich/*": "./src/enrich/*",
+    "#extract/*": "./src/extract/*",
+    "#graph-utl/*": "./src/graph-utl/*",
+    "#main/*": "./src/main/*",
+    "#meta": "./src/meta.js",
+    "#report/*": "./src/report/*",
+    "#utl/*": "./src/utl/*",
+    "#validate/*": "./src/validate/*"
+  },
   "exports": {
     ".": {
       "import": "./src/main/index.mjs",

src/cache/cache.mjs

@@ -1,11 +1,13 @@
 // @ts-check
 import { readFile, mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { scannableExtensions } from "../extract/transpile/meta.mjs";
-import { bus } from "../utl/bus.mjs";
 import { optionsAreCompatible } from "./options-compatible.mjs";
 import MetadataStrategy from "./metadata-strategy.mjs";
 import ContentStrategy from "./content-strategy.mjs";
+// @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
+import { scannableExtensions } from "#extract/transpile/meta.mjs";
+// @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
+import { bus } from "#utl/bus.mjs";
 
 const CACHE_FILE_NAME = "cache.json";
 
@@ -36,19 +38,19 @@ export default class Cache {
         pCruiseOptions,
         {
           extensions: new Set(
-            scannableExtensions.concat(pCruiseOptions.extraExtensionsToScan)
+            scannableExtensions.concat(pCruiseOptions.extraExtensionsToScan),
           ),
-        }
+        },
       ));
     bus.debug("cache: - comparing");
     return (
       this.cacheStrategy.revisionDataEqual(
         pCachedCruiseResult.revisionData,
-        this.revisionData
+        this.revisionData,
       ) &&
       optionsAreCompatible(
         pCachedCruiseResult.summary.optionsUsed,
-        pCruiseOptions
+        pCruiseOptions,
       )
     );
   }
@@ -60,7 +62,7 @@ export default class Cache {
   async read(pCacheFolder) {
     try {
       return JSON.parse(
-        await readFile(join(pCacheFolder, CACHE_FILE_NAME), "utf8")
+        await readFile(join(pCacheFolder, CACHE_FILE_NAME), "utf8"),
       );
     } catch (pError) {
       return { modules: [], summary: {} };
@@ -81,10 +83,10 @@ export default class Cache {
       JSON.stringify(
         this.cacheStrategy.prepareRevisionDataForSaving(
           pCruiseResult,
-          lRevisionData
-        )
+          lRevisionData,
+        ),
       ),
-      "utf8"
+      "utf8",
     );
   }
 }

src/cache/find-content-changes.mjs

@@ -1,15 +1,17 @@
 /* eslint-disable no-inline-comments */
 // @ts-check
 import { join } from "node:path/posix";
-import { bus } from "../utl/bus.mjs";
-import findAllFiles from "../utl/find-all-files.mjs";
 import {
   getFileHashSync,
   excludeFilter,
   includeOnlyFilter,
   hasInterestingExtension,
   moduleIsInterestingForDiff,
 } from "./helpers.mjs";
+// @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
+import { bus } from "#utl/bus.mjs";
+// @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
+import findAllFiles from "#utl/find-all-files.mjs";
 
 /**
  * @param {Set<string>} pFileSet
@@ -19,7 +21,7 @@ import {
 function diffCachedModuleAgainstFileSet(
   pFileSet,
   pBaseDirectory,
-  pFileHashFunction = getFileHashSync
+  pFileHashFunction = getFileHashSync,
 ) {
   return (pModule) => {
     if (!moduleIsInterestingForDiff(pModule)) {
@@ -31,7 +33,7 @@ function diffCachedModuleAgainstFileSet(
     }
 
     const lNewCheckSum = pFileHashFunction(
-      join(pBaseDirectory, pModule.source)
+      join(pBaseDirectory, pModule.source),
     );
     if (lNewCheckSum !== pModule.checksum) {
       return {
@@ -72,20 +74,20 @@ function diffCachedModuleAgainstFileSet(
 export default function findContentChanges(
   pDirectory,
   pCachedCruiseResult,
-  pOptions
+  pOptions,
 ) {
   bus.debug("cache: - getting revision data");
   const lFileSet = new Set(
     findAllFiles(pDirectory, {
       baseDir: pOptions.baseDir,
       excludeFilterFn: excludeFilter(pOptions.exclude),
       includeOnlyFilterFn: includeOnlyFilter(pOptions.includeOnly),
-    }).filter(hasInterestingExtension(pOptions.extensions))
+    }).filter(hasInterestingExtension(pOptions.extensions)),
   );
 
   bus.debug("cache: - getting (cached - new)");
   const lDiffCachedVsNew = pCachedCruiseResult.modules.map(
-    diffCachedModuleAgainstFileSet(lFileSet, pOptions.baseDir)
+    diffCachedModuleAgainstFileSet(lFileSet, pOptions.baseDir),
   );
 
   bus.debug("cache: - getting (new - cached)");

src/cache/helpers.mjs

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { extname } from "node:path";
 import memoize from "lodash/memoize.js";
-import { filenameMatchesPattern } from "../graph-utl/match-facade.mjs";
+import { filenameMatchesPattern } from "#graph-utl/match-facade.mjs";
 
 /**
  * @param {string} pString
@@ -101,10 +101,10 @@ export function hasInterestingExtension(pExtensions) {
 export function changeHasInterestingExtension(pExtensions) {
   return (pChange) => {
     const lNameHasInterestingExtension = hasInterestingExtension(pExtensions)(
-      pChange.name
+      pChange.name,
     );
     const lOldNameHasInterestingExtension = Boolean(
-      pChange.oldName && hasInterestingExtension(pExtensions)(pChange.oldName)
+      pChange.oldName && hasInterestingExtension(pExtensions)(pChange.oldName),
     );
     return lNameHasInterestingExtension || lOldNameHasInterestingExtension;
   };
@@ -128,7 +128,7 @@ const DEFAULT_INTERESTING_CHANGE_TYPES = new Set([
 export function isInterestingChangeType(pInterestingChangeTypes) {
   return (pChange) =>
     (pInterestingChangeTypes ?? DEFAULT_INTERESTING_CHANGE_TYPES).has(
-      pChange.changeType
+      pChange.changeType,
     );
 }
 

src/cache/metadata-strategy.mjs

@@ -2,14 +2,15 @@
 // @ts-check
 import { isDeepStrictEqual } from "node:util";
 import { getSHA, list } from "watskeburt";
-import { bus } from "../utl/bus.mjs";
 import {
   isInterestingChangeType,
   addCheckSumToChangeSync,
   excludeFilter,
   includeOnlyFilter,
   changeHasInterestingExtension,
 } from "./helpers.mjs";
+// @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
+import { bus } from "#utl/bus.mjs";
 
 export default class MetaDataStrategy {
   /**
@@ -27,7 +28,7 @@ export default class MetaDataStrategy {
     _pDirectory,
     _pCachedCruiseResult,
     pCruiseOptions,
-    pOptions
+    pOptions,
   ) {
     const lOptions = {
       shaRetrievalFn: getSHA,
@@ -45,7 +46,7 @@ export default class MetaDataStrategy {
       const lChanges = lDiff
         .filter(({ name }) => excludeFilter(pCruiseOptions.exclude)(name))
         .filter(({ name }) =>
-          includeOnlyFilter(pCruiseOptions.includeOnly)(name)
+          includeOnlyFilter(pCruiseOptions.includeOnly)(name),
         )
         .filter(changeHasInterestingExtension(lOptions.extensions))
         .filter(isInterestingChangeType(lOptions.interestingChangeTypes));
@@ -56,7 +57,7 @@ export default class MetaDataStrategy {
       };
     } catch (pError) {
       throw new Error(
-        `The --cache option works in concert with git - and it seems either the current folder isn't version managed or git isn't installed. Error:${`\n\n          ${pError}\n`}`
+        `The --cache option works in concert with git - and it seems either the current folder isn't version managed or git isn't installed. Error:${`\n\n          ${pError}\n`}`,
       );
     }
   }

src/cli/assert-node-environment-suitable.mjs

@@ -1,5 +1,5 @@
 import satisfies from "semver/functions/satisfies.js";
-import meta from "../meta.js";
+import meta from "#meta";
 
 export default function assertNodeEnvironmentSuitable(pNodeVersion) {
   // not using default parameter here because the check should run

src/cli/format-meta-info.mjs

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import figures from "figures";
 
-import { getAvailableTranspilers, allExtensions } from "../main/index.mjs";
+import { getAvailableTranspilers, allExtensions } from "#main/index.mjs";
 
 function bool2Symbol(pBool) {
   return pBool ? chalk.green(figures.tick) : chalk.red(figures.cross);
@@ -13,15 +13,15 @@ function formatTranspilers() {
       `${pAll}    ${bool2Symbol(pThis.available)} ${pThis.name} (${
         pThis.version
       })\n`,
-    `    ${bool2Symbol(true)} javascript (>es1)\n`
+    `    ${bool2Symbol(true)} javascript (>es1)\n`,
   );
 }
 
 function formatExtensions(pExtensions) {
   return pExtensions.reduce(
     (pAll, pThis) =>
       `${pAll}    ${bool2Symbol(pThis.available)} ${pThis.extension}\n`,
-    ""
+    "",
   );
 }
 
@@ -30,7 +30,7 @@ export default function formatMetaInfo() {
   Supported:
 
     If you need a supported, but not enabled transpiler ('${chalk.red(
-      figures.cross
+      figures.cross,
     )}' below), just install
     it in the same folder dependency-cruiser is installed. E.g. 'npm i livescript'
     will enable livescript support if it's installed in your project folder.

src/cli/format.mjs

@@ -1,7 +1,7 @@
-import _format from "../main/format.mjs";
 import assertFileExistence from "./utl/assert-file-existence.mjs";
 import normalizeOptions from "./normalize-cli-options.mjs";
 import { getInStream, write } from "./utl/io.mjs";
+import _format from "#main/format.mjs";
 
 /**
  *

src/cli/index.mjs

@@ -4,15 +4,14 @@ import set from "lodash/set.js";
 import isInstalledGlobally from "is-installed-globally";
 import chalk from "chalk";
 
-import cruise from "../main/cruise.mjs";
-import { INFO, bus } from "../utl/bus.mjs";
-
 import assertFileExistence from "./utl/assert-file-existence.mjs";
 import normalizeCliOptions from "./normalize-cli-options.mjs";
 import { write } from "./utl/io.mjs";
 import setUpCliFeedbackListener from "./listeners/cli-feedback.mjs";
 import setUpPerformanceLogListener from "./listeners/performance-log/index.mjs";
 import setUpNDJSONListener from "./listeners/ndjson.mjs";
+import cruise from "#main/cruise.mjs";
+import { INFO, bus } from "#utl/bus.mjs";
 
 async function extractResolveOptions(pCruiseOptions) {
   let lResolveOptions = {};
@@ -21,7 +20,7 @@ async function extractResolveOptions(pCruiseOptions) {
 
   if (lWebPackConfigFileName) {
     const { default: extractWebpackResolveConfig } = await import(
-      "../config-utl/extract-webpack-resolve-config.mjs"
+      "#config-utl/extract-webpack-resolve-config.mjs"
     );
     lResolveOptions = await extractWebpackResolveConfig(
       lWebPackConfigFileName,
@@ -35,7 +34,7 @@ async function extractResolveOptions(pCruiseOptions) {
 async function addKnownViolations(pCruiseOptions) {
   if (pCruiseOptions.knownViolationsFile) {
     const { default: extractKnownViolations } = await import(
-      "../config-utl/extract-known-violations.mjs"
+      "#config-utl/extract-known-violations.mjs"
     );
     const lKnownViolations = await extractKnownViolations(
       pCruiseOptions.knownViolationsFile,
@@ -57,7 +56,7 @@ async function extractTSConfigOptions(pCruiseOptions) {
 
   if (lTSConfigFileName) {
     const { default: extractTSConfig } = await import(
-      "../config-utl/extract-ts-config.mjs"
+      "#config-utl/extract-ts-config.mjs"
     );
     lReturnValue = extractTSConfig(lTSConfigFileName);
   }
@@ -71,7 +70,7 @@ async function extractBabelConfigOptions(pCruiseOptions) {
     pCruiseOptions?.ruleSet?.options?.babelConfig?.fileName ?? null;
   if (lBabelConfigFileName) {
     const { default: extractBabelConfig } = await import(
-      "../config-utl/extract-babel-config.mjs"
+      "#config-utl/extract-babel-config.mjs"
     );
     lReturnValue = extractBabelConfig(lBabelConfigFileName);
   }