dependency-cruiser 16.0.0-beta-3 → 16.0.0-beta-5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "16.0.0-beta-3",
+  "version": "16.0.0-beta-5",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",

package/src/cache/cache.mjs

@@ -14,6 +14,13 @@ 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";
 
+/**
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionData} IRevisionData
+ * @typedef {import("../../types/strict-options.mjs").IStrictCruiseOptions} IStrictCruiseOptions
+ * @typedef {import("../../types/dependency-cruiser.mjs").ICruiseResult} ICruiseResult
+ * @typedef {import("../../types/cache-options.mjs").cacheStrategyType} cacheStrategyType
+ */
+
 const CACHE_FILE_NAME = "cache.json";
 const EMPTY_CACHE = {
   modules: [],
@@ -27,10 +34,21 @@ const EMPTY_CACHE = {
     optionsUsed: {},
   },
 };
+// Bump this to the current major.minor version when the cache format changes in
+// a way that's not backwards compatible.
+// e.g. version 3.0.0 => 3
+//     version 3.1.0 => 3.1
+//     version 3.1.1 => 3.1
+//     version 3.11.0 => 3.11
+// This means we assume breaking cache format versions won't occur
+// in patch releases. If worst case scenario it _is_ necessary we could
+// add the patch version divided by 1000_000 e.g.:
+//     version 3.14.16 => 3.14 + 16/1000_000 = 3.140016
+const CACHE_FORMAT_VERSION = 16;
 
 export default class Cache {
   /**
-   * @param {import("../../types/cache-options.js").cacheStrategyType=} pCacheStrategy
+   * @param {cacheStrategyType=} pCacheStrategy
    * @param {boolean=} pCompress
    */
   constructor(pCacheStrategy, pCompress) {
@@ -42,10 +60,17 @@ export default class Cache {
     this.compress = pCompress ?? false;
   }
 
+  cacheFormatVersionCompatible(pCachedCruiseResult) {
+    return (
+      (pCachedCruiseResult?.revisionData?.cacheFormatVersion ?? 1) >=
+      CACHE_FORMAT_VERSION
+    );
+  }
+
   /**
-   * @param {import("../../types/strict-options.js").IStrictCruiseOptions} pCruiseOptions
-   * @param {import("../../types/dependency-cruiser.js").ICruiseResult} pCachedCruiseResult
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pRevisionData
+   * @param {IStrictCruiseOptions} pCruiseOptions
+   * @param {ICruiseResult} pCachedCruiseResult
+   * @param {IRevisionData=} pRevisionData
    * @returns {Promise<boolean>}
    */
   async canServeFromCache(pCruiseOptions, pCachedCruiseResult, pRevisionData) {
@@ -61,15 +86,15 @@ export default class Cache {
           ),
         },
       ));
+    this.revisionData.cacheFormatVersion = CACHE_FORMAT_VERSION;
     bus.debug("cache: - comparing");
     return (
+      this.cacheFormatVersionCompatible(pCachedCruiseResult) &&
       this.cacheStrategy.revisionDataEqual(
         pCachedCruiseResult.revisionData,
         this.revisionData,
       ) &&
       optionsAreCompatible(
-        // @ts-expect-error ts(2345) - it's indeed not strict cruise options,
-        // but it will do for now (_it works_)
         pCachedCruiseResult.summary.optionsUsed,
         pCruiseOptions,
       )
@@ -78,7 +103,7 @@ export default class Cache {
 
   /**
    * @param {string} pCacheFolder
-   * @returns {Promise<import("../../types/dependency-cruiser.js").ICruiseResult>}
+   * @returns {Promise<ICruiseResult>}
    */
   async read(pCacheFolder) {
     try {
@@ -133,11 +158,11 @@ export default class Cache {
 
   /**
    * @param {string} pCacheFolder
-   * @param {import("../../types/dependency-cruiser.js").ICruiseResult} pCruiseResult
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pRevisionData
+   * @param {ICruiseResult} pCruiseResult
+   * @param {IRevisionData=} pRevisionData
    */
   async write(pCacheFolder, pCruiseResult, pRevisionData) {
-    const lRevisionData = pRevisionData ?? this.revisionData;
+    let lRevisionData = pRevisionData ?? this.revisionData;
 
     await mkdir(pCacheFolder, { recursive: true });
     const lUncompressedPayload = JSON.stringify(

package/src/cache/content-strategy.mjs

@@ -9,9 +9,17 @@ import {
   moduleIsInterestingForDiff,
 } from "./helpers.mjs";
 
+/**
+ * @typedef {import("../../types/dependency-cruiser.mjs").IModule} IModule
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionChange} IRevisionChange
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionData} IRevisionData
+ * @typedef {import("../../types/dependency-cruiser.mjs").ICruiseResult} ICruiseResult
+ * @typedef {import("../../types/strict-options.mjs").IStrictCruiseOptions} IStrictCruiseOptions
+ */
+
 /**
  * @param {string} pBaseDirectory
- * @returns {(pModule: import("../../types/dependency-cruiser.js").IModule) => import("../../types/dependency-cruiser.js").IModule}
+ * @returns {(IModule) => IModule}
  */
 function addCheckSumToModule(pBaseDirectory) {
   return (pModule) => {
@@ -26,9 +34,9 @@ function addCheckSumToModule(pBaseDirectory) {
 }
 
 /**
- * @param {import("../../types/dependency-cruiser.js").IRevisionChange[]} pChanges
- * @param {import("../../types/dependency-cruiser.js").IModule[]} pModules
- * @returns {import("../../types/dependency-cruiser.js").IRevisionChange[]}
+ * @param {IRevisionChange[]} pChanges
+ * @param {IModule[]} pModules
+ * @returns {IRevisionChange[]}
  */
 function refreshChanges(pChanges, pModules) {
   return pChanges.filter(
@@ -44,15 +52,15 @@ function refreshChanges(pChanges, pModules) {
 export default class ContentStrategy {
   /**
    * @param {string} pDirectory
-   * @param {import("../../types/dependency-cruiser.js").ICruiseResult} pCachedCruiseResult
-   * @param {import("../../types/strict-options.js").IStrictCruiseOptions} pCruiseOptions
+   * @param {ICruiseResult} pCachedCruiseResult
+   * @param {IStrictCruiseOptions} pCruiseOptions
    * @param {Object} pOptions
    * @param {Set<string>} pOptions.extensions
    * @param {Set<import("watskeburt").changeTypeType>=} pOptions.interestingChangeTypes?
    * @param {string=} pOptions.baseDir
    * @param {typeof findContentChanges=} pOptions.diffListFn
    * @param {typeof import('watskeburt').getSHA=} pOptions.checksumFn
-   * @returns {import("../../types/dependency-cruiser.js").IRevisionData}
+   * @returns {IRevisionData}
    */
   getRevisionData(pDirectory, pCachedCruiseResult, pCruiseOptions, pOptions) {
     const lOptions = {
@@ -62,21 +70,20 @@ export default class ContentStrategy {
     };
     return {
       SHA1: "unknown-in-content-cache-strategy",
-      changes:
-        /** @type {import("../../types/dependency-cruiser.js").IRevisionChange[]} */ (
-          lOptions.diffListFn(pDirectory, pCachedCruiseResult, {
-            baseDir: lOptions.baseDir,
-            extensions: lOptions.extensions,
-            includeOnly: pCruiseOptions.includeOnly,
-            exclude: pCruiseOptions.exclude,
-          })
-        ).filter(isInterestingChangeType(lOptions.interestingChangeTypes)),
+      changes: /** @type {IRevisionChange[]} */ (
+        lOptions.diffListFn(pDirectory, pCachedCruiseResult, {
+          baseDir: lOptions.baseDir,
+          extensions: lOptions.extensions,
+          includeOnly: pCruiseOptions.includeOnly,
+          exclude: pCruiseOptions.exclude,
+        })
+      ).filter(isInterestingChangeType(lOptions.interestingChangeTypes)),
     };
   }
 
   /**
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pExistingRevisionData
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pNewRevisionData
+   * @param {IRevisionData=} pExistingRevisionData
+   * @param {IRevisionData=} pNewRevisionData
    * @returns {boolean}
    */
   revisionDataEqual(pExistingRevisionData, pNewRevisionData) {
@@ -95,13 +102,13 @@ export default class ContentStrategy {
   }
 
   /**
-   * @param {import("../../types/dependency-cruiser.js").ICruiseResult} pCruiseResult
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pRevisionData
-   * @returns {import("../../types/dependency-cruiser.js").ICruiseResult}
+   * @param {ICruiseResult} pCruiseResult
+   * @param {IRevisionData=} pRevisionData
+   * @returns {ICruiseResult}
    */
   prepareRevisionDataForSaving(pCruiseResult, pRevisionData) {
     const lModulesWithCheckSum = pCruiseResult.modules.map(
-      addCheckSumToModule(pCruiseResult.summary.optionsUsed.baseDir),
+      addCheckSumToModule(pCruiseResult.summary.optionsUsed.baseDir || "."),
     );
     const lRevisionData = {
       ...pRevisionData,

package/src/cache/find-content-changes.mjs

@@ -69,8 +69,8 @@ function diffCachedModuleAgainstFileSet(
  * @param {Object} pOptions
  * @param {Set<string>} pOptions.extensions
  * @param {string} pOptions.baseDir
- * @param {import("../../types/strict-filter-types").IStrictExcludeType} pOptions.exclude
- * @param {import("../../types/strict-filter-types").IStrictIncludeOnlyType=} pOptions.includeOnly
+ * @param {import("../../types/strict-filter-types.mjs").IStrictExcludeType} pOptions.exclude
+ * @param {import("../../types/strict-filter-types.mjs").IStrictIncludeOnlyType=} pOptions.includeOnly
  * @returns {import("../..").IRevisionChange[]}
  */
 export default function findContentChanges(

package/src/cache/helpers.mjs

@@ -6,6 +6,13 @@ import memoize from "lodash/memoize.js";
 // @ts-expect-error ts(2307) - the ts compiler is not privy to the existence of #imports in package.json
 import { filenameMatchesPattern } from "#graph-utl/match-facade.mjs";
 
+/**
+ * @typedef {import("../..").IModule} IModule
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionChange} IRevisionChange
+ * @typedef {import("../../types/filter-types.mjs").IExcludeType} IExcludeType
+ * @typedef {import("../../types/strict-filter-types.mjs").IStrictIncludeOnlyType} IStrictIncludeOnlyType
+ */
+
 /**
  * @param {string} pString
  * @returns {string}
@@ -30,7 +37,7 @@ export const getFileHashSync = memoize(_getFileHashSync);
 
 /**
  * @param {import("watskeburt").IChange} pChange
- * @param {import("../../types/dependency-cruiser.js").IRevisionChange}
+ * @return {IRevisionChange}
  */
 export function addCheckSumToChangeSync(pChange) {
   return {
@@ -40,8 +47,7 @@ export function addCheckSumToChangeSync(pChange) {
 }
 
 /**
- *
- * @param {import("../../types/filter-types.js").IExcludeType} pExcludeOption
+ * @param {IExcludeType} pExcludeOption
  * @returns {(pFileName: string) => boolean}
  */
 export function excludeFilter(pExcludeOption) {
@@ -54,7 +60,7 @@ export function excludeFilter(pExcludeOption) {
 }
 
 /**
- * @param {import("../../types/strict-filter-types.js").IStrictIncludeOnlyType=} pIncludeOnlyFilter
+ * @param {IStrictIncludeOnlyType=} pIncludeOnlyFilter
  * @returns {(pFileName: string) => boolean}
  */
 export function includeOnlyFilter(pIncludeOnlyFilter) {
@@ -112,7 +118,8 @@ export function isInterestingChangeType(pInterestingChangeTypes) {
 }
 
 /**
- * @param {import("../..").IModule} pModule
+ * @param {IModule} pModule
+ * @returns {boolean}
  */
 export function moduleIsInterestingForDiff(pModule) {
   return (

package/src/cache/metadata-strategy.mjs

@@ -12,6 +12,14 @@ import {
 // @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";
 
+/**
+ * @typedef {import("../../types/dependency-cruiser.mjs").IModule} IModule
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionChange} IRevisionChange
+ * @typedef {import("../../types/dependency-cruiser.mjs").IRevisionData} IRevisionData
+ * @typedef {import("../../types/dependency-cruiser.mjs").ICruiseResult} ICruiseResult
+ * @typedef {import("../../types/strict-options.mjs").IStrictCruiseOptions} IStrictCruiseOptions
+ */
+
 export default class MetaDataStrategy {
   /**
    * @param {string} _pDirectory
@@ -22,7 +30,7 @@ export default class MetaDataStrategy {
    * @param {typeof getSHA=} pOptions.shaRetrievalFn
    * @param {typeof list=} pOptions.diffListFn
    * @param {typeof addCheckSumToChangeSync=} pOptions.checksumFn
-   * @returns {Promise<import("../../types/dependency-cruiser.js").IRevisionData>}
+   * @returns {Promise<IRevisionData>}
    */
   async getRevisionData(
     _pDirectory,
@@ -63,8 +71,8 @@ export default class MetaDataStrategy {
   }
 
   /**
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pExistingRevisionData
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pNewRevisionData
+   * @param {IRevisionData=} pExistingRevisionData
+   * @param {IRevisionData=} pNewRevisionData
    * @returns {boolean}
    */
   revisionDataEqual(pExistingRevisionData, pNewRevisionData) {
@@ -81,9 +89,9 @@ export default class MetaDataStrategy {
   }
 
   /**
-   * @param {import("../../types/dependency-cruiser.js").ICruiseResult} pCruiseResult
-   * @param {import("../../types/dependency-cruiser.js").IRevisionData=} pRevisionData
-   * @returns {import("../../types/dependency-cruiser.js").ICruiseResult}
+   * @param {ICruiseResult} pCruiseResult
+   * @param {IRevisionData=} pRevisionData
+   * @returns {ICruiseResult}
    */
   prepareRevisionDataForSaving(pCruiseResult, pRevisionData) {
     return pRevisionData

package/src/cache/options-compatible.mjs

@@ -1,6 +1,10 @@
 // @ts-check
 import { isDeepStrictEqual } from "node:util";
 
+/**
+ * @typedef {import("../../types/strict-options.mjs").IStrictCruiseOptions} IStrictCruiseOptions
+ */
+
 /*
 # command line options
 ## No influence on cache
@@ -88,8 +92,8 @@ export function cacheOptionIsCompatible(pExistingCacheOption, pNewCacheOption) {
 
 /**
  *
- * @param {import("../../types/strict-options").IStrictCruiseOptions} pOldOptions
- * @param {import("../../types/strict-options").IStrictCruiseOptions} pNewOptions
+ * @param {IStrictCruiseOptions} pOldOptions
+ * @param {IStrictCruiseOptions} pNewOptions
  * @returns {boolean}
  */
 // eslint-disable-next-line complexity
@@ -105,11 +109,11 @@ export function optionsAreCompatible(pOldOptions, pNewOptions) {
     includeOnlyIsCompatible(pOldOptions.includeOnly, pNewOptions.includeOnly) &&
     filterOptionIsCompatible(
       pOldOptions.doNotFollow,
-      pNewOptions.doNotFollow
+      pNewOptions.doNotFollow,
     ) &&
     filterOptionIsCompatible(
       pOldOptions.moduleSystems,
-      pNewOptions.moduleSystems
+      pNewOptions.moduleSystems,
     ) &&
     filterOptionIsCompatible(pOldOptions.exclude, pNewOptions.exclude) &&
     filterOptionIsCompatible(pOldOptions.focus, pNewOptions.focus) &&
@@ -119,15 +123,15 @@ export function optionsAreCompatible(pOldOptions, pNewOptions) {
     limitIsCompatible(pOldOptions.maxDepth, pNewOptions.maxDepth) &&
     optionIsCompatible(
       pOldOptions.knownViolations || [],
-      pNewOptions.knownViolations || []
+      pNewOptions.knownViolations || [],
     ) &&
     optionIsCompatible(
       pOldOptions.enhancedResolveOptions,
-      pNewOptions.enhancedResolveOptions
+      pNewOptions.enhancedResolveOptions,
     ) &&
     optionIsCompatible(
       pOldOptions.exoticRequireStrings,
-      pNewOptions.exoticRequireStrings
+      pNewOptions.exoticRequireStrings,
     ) &&
     cacheOptionIsCompatible(pOldOptions.cache, pNewOptions.cache)
   );

package/src/config-utl/extract-known-violations.mjs

@@ -2,15 +2,55 @@ import { readFile } from "node:fs/promises";
 import json5 from "json5";
 import makeAbsolute from "./make-absolute.mjs";
 
+/**
+ * @typedef {import("../../types/violations.d.mjs").IViolation} IViolation
+ * @typedef {import("../../types/shared-types.d.mts").DependencyType} DependencyType
+ *
+ * @typedef {IViolation & {cycle: Array<{name: string, dependencyTypes: Array<DependencyType>}>} | {cycle: Array<DependencyType>}} IMaybeOldFormatViolation
+ */
+
+/**
+ * cycles went from Array<string> to Array<{name: string, dependencyTypes: Array<DependencyType>}>
+ * in version 16.0.0. Known violations would typically be still in the old
+ * format. To prevent customers from bumping into error messages and having
+ * to update or regenerate their known violations, we'll make the old format
+ * forward compatible with this.
+ *
+ * @param {IMaybeOldFormatViolation} pKnownViolation
+ * @returns {IViolation}
+ */
+function makeForwardCompatible(pKnownViolation) {
+  if (Boolean(pKnownViolation.cycle)) {
+    return {
+      ...pKnownViolation,
+      cycle: pKnownViolation.cycle.map((pModule) => {
+        if (Boolean(pModule.name)) {
+          return pModule;
+        }
+        return {
+          name: pModule,
+          dependencyTypes: [],
+        };
+      }),
+    };
+  }
+  return pKnownViolation;
+}
+
 export default async function extractKnownViolations(pKnownViolationsFileName) {
   try {
-    return json5.parse(
-      await readFile(makeAbsolute(pKnownViolationsFileName), "utf8")
+    const lFileContents = await readFile(
+      makeAbsolute(pKnownViolationsFileName),
+      "utf8",
     );
+    const lKnownViolations = json5.parse(lFileContents);
+    const lForwardCompatible = lKnownViolations.map(makeForwardCompatible);
+
+    return lForwardCompatible;
   } catch (pError) {
     if (pError instanceof SyntaxError) {
       throw new SyntaxError(
-        `'${pKnownViolationsFileName}' should be valid json\n          ${pError}`
+        `'${pKnownViolationsFileName}' should be valid json\n          ${pError}`,
       );
     }
     throw pError;

package/src/enrich/derive/circular.mjs

@@ -4,17 +4,13 @@ function addCircularityCheckToDependency(
   pIndexedGraph,
   pFrom,
   pToDep,
-  pDependencyName
+  pDependencyName,
 ) {
   let lReturnValue = {
     ...pToDep,
     circular: false,
   };
-  const lCycle = pIndexedGraph.getCycle(
-    pFrom,
-    pToDep[pDependencyName],
-    pDependencyName
-  );
+  const lCycle = pIndexedGraph.getCycle(pFrom, pToDep[pDependencyName]);
 
   if (lCycle.length > 0) {
     lReturnValue = {
@@ -35,7 +31,7 @@ function addCircularityCheckToDependency(
 export default function detectAndAddCycles(
   pNodes,
   pIndexedNodes,
-  { pSourceAttribute, pDependencyName }
+  { pSourceAttribute, pDependencyName },
 ) {
   return pNodes.map((pModule) => ({
     ...pModule,
@@ -44,8 +40,8 @@ export default function detectAndAddCycles(
         pIndexedNodes,
         pModule[pSourceAttribute],
         pToDep,
-        pDependencyName
-      )
+        pDependencyName,
+      ),
     ),
   }));
 }

package/src/enrich/derive/metrics/get-module-metrics.mjs

@@ -20,7 +20,7 @@ function addInstabilityToDependency(pAllModules) {
   return (pDependency) => ({
     ...pDependency,
     instability:
-      (lIndexedModules.findModuleByName(pDependency.resolved) || {})
+      (lIndexedModules.findVertexByName(pDependency.resolved) || {})
         .instability || 0,
   });
 }

package/src/enrich/summarize/is-same-violation.mjs

@@ -1,3 +1,7 @@
+function pluckName({ name }) {
+  return name;
+}
+
 export default function isSameViolation(pLeftViolation, pRightViolation) {
   let lReturnValue = false;
 
@@ -5,9 +9,11 @@ export default function isSameViolation(pLeftViolation, pRightViolation) {
     if (pRightViolation.cycle && pLeftViolation.cycle) {
       lReturnValue =
         pLeftViolation.cycle.length === pRightViolation.cycle.length &&
-        pLeftViolation.cycle.every((pModule) =>
-          pRightViolation.cycle.includes(pModule)
-        );
+        pLeftViolation.cycle
+          .map(pluckName)
+          .every((pModule) =>
+            pRightViolation.cycle.map(pluckName).includes(pModule),
+          );
     } else {
       lReturnValue =
         pLeftViolation.from === pRightViolation.from &&

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

@@ -1,3 +1,4 @@
+/* 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";
@@ -219,6 +220,8 @@ function stripIndex(pModulePath) {
  *
  * https://www.typescriptlang.org/docs/handbook/modules/reference.html#baseurl
  *
+ * Assumes the pModuleName is not relative.
+ *
  * @param {string} pModuleName
  * @param {string} pResolvedModuleName
  * @param {string} pTSConfigBaseURL
@@ -228,7 +231,13 @@ function matchesTSConfigBaseURL(
   pResolvedModuleName,
   pTSConfigBaseURL,
 ) {
-  if (!pTSConfigBaseURL) {
+  // the pModuleName === pResolvedModuleName check is there to prevent
+  // false positives for core modules ('fs' resolved === 'fs') and modules that
+  // we couldn't resolve at all (e.g. 'this/does/not/exist' => 'this/does/not/exist')
+  //
+  // we could also check whether the moduleName is relative, but that's
+  // not efficient as that was already done before this function was called.
+  if (!pTSConfigBaseURL || pModuleName === pResolvedModuleName) {
     return false;
   }
   // "If baseUrl is set, TypeScript will resolve non-relative module names