dependency-cruiser 10.8.0 → 11.2.0

package/src/utl/regex-util.js

@@ -0,0 +1,57 @@
+/**
+ * If there is at least one group expression in the given pRulePath
+ * return the first matched one.
+ *
+ * Return null in all other cases.
+ *
+ * This fills our current need. Later we can expand it to return all group
+ * matches.
+ *
+ * @param {import("../../types/rule-set").IFromRestriction} pFromRestriction
+ * @param {string} pActualPath
+ * @returns {string[]|null}
+ */
+function extractGroups(pFromRestriction, pActualPath) {
+  let lReturnValue = [];
+
+  if (Boolean(pFromRestriction.path)) {
+    let lMatchResult = pActualPath.match(pFromRestriction.path);
+
+    if (Boolean(lMatchResult) && lMatchResult.length > 1) {
+      lReturnValue = lMatchResult.filter(
+        (pResult) => typeof pResult === "string"
+      );
+    }
+  }
+  return lReturnValue;
+}
+
+/**
+ *
+ * Examples:
+ * replaceGroupPlaceholders("./src/components/$1", ["wholematch", "lala-component"]) =>
+ *   './src/components/lala-component'
+ *
+ * replaceGroupPlaceholders("./test/components/$1/$2.spec.js$", ["wholematch", "lala-component", "things"]) =>
+ *   './test/components/lala-component/things.spec.js$'
+ *
+ * @param {string} pString
+ * @param {string[]} pExtractedGroups - note that when using the result of a
+ * regex match, the 0th index contains the whole matched string and indices
+ * > 1 contain matched groups
+ * @returns {string} pString with the matching groups replaced with the
+ * groups from pExtractedgroups
+ */
+function replaceGroupPlaceholders(pString, pExtractedGroups) {
+  return pExtractedGroups.reduce(
+    (pAll, pThis, pIndex) =>
+      // eslint-disable-next-line security/detect-non-literal-regexp
+      pAll.replace(new RegExp(`\\$${pIndex}`, "g"), pThis),
+    pString
+  );
+}
+
+module.exports = {
+  extractGroups,
+  replaceGroupPlaceholders,
+};

package/src/validate/match-dependency-rule.js

@@ -1,25 +1,6 @@
-const _has = require("lodash/has");
+const { extractGroups } = require("../utl/regex-util");
 const isModuleOnlyRule = require("./is-module-only-rule");
 const matchers = require("./matchers");
-const { extractGroups } = require("./utl");
-
-function propertyEquals(pTo, pRule, pProperty) {
-  // ignore security/detect-object-injection because:
-  // - we only use it from within the module with two fixed values
-  // - the propertyEquals function is not exposed externaly
-  return _has(pRule.to, pProperty)
-    ? // eslint-disable-next-line security/detect-object-injection
-      pTo[pProperty] === pRule.to[pProperty]
-    : true;
-}
-
-function matchesMoreThanOneDependencyType(pRuleTo, pTo) {
-  if (_has(pRuleTo, "moreThanOneDependencyType")) {
-    return pRuleTo.moreThanOneDependencyType === pTo.dependencyTypes.length > 1;
-  }
-
-  return true;
-}
 
 function match(pFrom, pTo) {
   // eslint-disable-next-line complexity
@@ -33,22 +14,28 @@ function match(pFrom, pTo) {
       matchers.toPathNot(pRule, pTo, lGroups) &&
       matchers.toDependencyTypes(pRule, pTo) &&
       matchers.toDependencyTypesNot(pRule, pTo) &&
-      matchesMoreThanOneDependencyType(pRule.to, pTo) &&
-      matchers.toLicense(pRule, pTo) &&
-      matchers.toLicenseNot(pRule, pTo) &&
-      matchers.toExoticRequire(pRule, pTo) &&
-      matchers.toExoticRequireNot(pRule, pTo) &&
-      matchers.toVia(pRule, pTo) &&
-      matchers.toViaNot(pRule, pTo) &&
+      matchers.matchesMoreThanOneDependencyType(pRule, pTo) &&
       // preCompilationOnly is not a mandatory attribute, but if the attribute
       // is in the rule but not in the dependency there won't be a match
       // anyway, so we can use the default propertyEquals method regardless
-      propertyEquals(pTo, pRule, "preCompilationOnly") &&
+      matchers.propertyEquals(pRule, pTo, "preCompilationOnly") &&
       // couldNotResolve, circular, dynamic and exoticallyRequired _are_ mandatory
-      propertyEquals(pTo, pRule, "couldNotResolve") &&
-      propertyEquals(pTo, pRule, "circular") &&
-      propertyEquals(pTo, pRule, "dynamic") &&
-      propertyEquals(pTo, pRule, "exoticallyRequired")
+      matchers.propertyEquals(pRule, pTo, "couldNotResolve") &&
+      matchers.propertyEquals(pRule, pTo, "circular") &&
+      matchers.propertyEquals(pRule, pTo, "dynamic") &&
+      matchers.propertyEquals(pRule, pTo, "exoticallyRequired") &&
+      matchers.propertyMatches(pRule, pTo, "license", "license") &&
+      matchers.propertyMatchesNot(pRule, pTo, "licenseNot", "license") &&
+      matchers.propertyMatches(pRule, pTo, "exoticRequire", "exoticRequire") &&
+      matchers.propertyMatchesNot(
+        pRule,
+        pTo,
+        "exoticRequireNot",
+        "exoticRequire"
+      ) &&
+      matchers.toVia(pRule, pTo) &&
+      matchers.toViaNot(pRule, pTo) &&
+      matchers.toIsMoreUnstable(pRule, pFrom, pTo)
     );
   };
 }

package/src/validate/match-module-rule.js

@@ -1,7 +1,7 @@
 const _has = require("lodash/has");
+const { extractGroups } = require("../utl/regex-util");
 const isModuleOnlyRule = require("./is-module-only-rule");
 const matchers = require("./matchers");
-const { extractGroups } = require("./utl");
 
 function matchesOrphanRule(pRule, pModule) {
   return (

package/src/validate/matchers.js

@@ -1,4 +1,31 @@
+/* eslint-disable security/detect-object-injection */
+const _has = require("lodash/has");
 const { intersects } = require("../utl/array-util");
+const { replaceGroupPlaceholders } = require("../utl/regex-util");
+
+function propertyEquals(pRule, pDependency, pProperty) {
+  // The properties can be booleans, so we can't use !pRule.to[pProperty]
+  if (_has(pRule.to, pProperty)) {
+    return pDependency[pProperty] === pRule.to[pProperty];
+  }
+  return true;
+}
+
+function propertyMatches(pRule, pDependency, pRuleProperty, pProperty) {
+  return Boolean(
+    !pRule.to[pRuleProperty] ||
+      (pDependency[pProperty] &&
+        pDependency[pProperty].match(pRule.to[pRuleProperty]))
+  );
+}
+
+function propertyMatchesNot(pRule, pDependency, pRuleProperty, pProperty) {
+  return Boolean(
+    !pRule.to[pRuleProperty] ||
+      (pDependency[pProperty] &&
+        !pDependency[pProperty].match(pRule.to[pRuleProperty]))
+  );
+}
 
 function fromPath(pRule, pModule) {
   return Boolean(!pRule.from.path || pModule.source.match(pRule.from.path));
@@ -20,20 +47,11 @@ function modulePathNot(pRule, pModule) {
   );
 }
 
-function _replaceGroupPlaceholders(pString, pExtractedGroups) {
-  return pExtractedGroups.reduce(
-    (pAll, pThis, pIndex) =>
-      // eslint-disable-next-line security/detect-non-literal-regexp
-      pAll.replace(new RegExp(`\\$${pIndex}`, "g"), pThis),
-    pString
-  );
-}
-
 function _toPath(pRule, pString, pGroups = []) {
   return Boolean(
     !pRule.to.path ||
       (pGroups.length > 0
-        ? pString.match(_replaceGroupPlaceholders(pRule.to.path, pGroups))
+        ? pString.match(replaceGroupPlaceholders(pRule.to.path, pGroups))
         : pString.match(pRule.to.path))
   );
 }
@@ -50,7 +68,7 @@ function _toPathNot(pRule, pString, pGroups = []) {
   return (
     !Boolean(pRule.to.pathNot) ||
     !(pGroups.length > 0
-      ? pString.match(_replaceGroupPlaceholders(pRule.to.pathNot, pGroups))
+      ? pString.match(replaceGroupPlaceholders(pRule.to.pathNot, pGroups))
       : pString.match(pRule.to.pathNot))
   );
 }
@@ -77,33 +95,11 @@ function toDependencyTypesNot(pRule, pDependency) {
   );
 }
 
-function toLicense(pRule, pDependency) {
-  return Boolean(
-    !pRule.to.license ||
-      (pDependency.license && pDependency.license.match(pRule.to.license))
-  );
-}
-
-function toLicenseNot(pRule, pDependency) {
-  return Boolean(
-    !pRule.to.licenseNot ||
-      (pDependency.license && !pDependency.license.match(pRule.to.licenseNot))
-  );
-}
-
-function toExoticRequire(pRule, pDependency) {
-  return Boolean(
-    !pRule.to.exoticRequire ||
-      (pDependency.exoticRequire &&
-        pDependency.exoticRequire.match(pRule.to.exoticRequire))
-  );
-}
-
-function toExoticRequireNot(pRule, pDependency) {
+function toVia(pRule, pDependency) {
   return Boolean(
-    !pRule.to.exoticRequireNot ||
-      (pDependency.exoticRequire &&
-        !pDependency.exoticRequire.match(pRule.to.exoticRequireNot))
+    !pRule.to.via ||
+      (pDependency.cycle &&
+        pDependency.cycle.some((pVia) => pVia.match(pRule.to.via)))
   );
 }
 
@@ -115,16 +111,32 @@ function toViaNot(pRule, pDependency) {
   );
 }
 
-function toVia(pRule, pDependency) {
-  return Boolean(
-    !pRule.to.via ||
-      (pDependency.cycle &&
-        pDependency.cycle.some((pVia) => pVia.match(pRule.to.via)))
-  );
+function toIsMoreUnstable(pRule, pModule, pDependency) {
+  if (_has(pRule, "to.moreUnstable")) {
+    return (
+      (pRule.to.moreUnstable &&
+        pModule.instability < pDependency.instability) ||
+      (!pRule.to.moreUnstable && pModule.instability >= pDependency.instability)
+    );
+  }
+  return true;
+}
+
+function matchesMoreThanOneDependencyType(pRule, pDependency) {
+  if (_has(pRule.to, "moreThanOneDependencyType")) {
+    return (
+      pRule.to.moreThanOneDependencyType ===
+      pDependency.dependencyTypes.length > 1
+    );
+  }
+  return true;
 }
 
 module.exports = {
-  _replaceGroupPlaceholders,
+  replaceGroupPlaceholders,
+  propertyEquals,
+  propertyMatches,
+  propertyMatchesNot,
   fromPath,
   fromPathNot,
   toPath,
@@ -135,10 +147,8 @@ module.exports = {
   toModulePathNot,
   toDependencyTypes,
   toDependencyTypesNot,
-  toLicense,
-  toLicenseNot,
-  toExoticRequire,
-  toExoticRequireNot,
   toVia,
   toViaNot,
+  toIsMoreUnstable,
+  matchesMoreThanOneDependencyType,
 };

package/src/validate/violates-required-rule.js

@@ -1,5 +1,5 @@
+const { extractGroups } = require("../utl/regex-util");
 const matchers = require("./matchers");
-const { extractGroups } = require("./utl");
 
 /**
  * Returns true if the module violates the rule.

package/types/baseline-violations.d.ts

@@ -1,3 +1,3 @@
-import { IViolation } from "./cruise-result";
+import { IViolation } from "./violations";
 
 export type IBaselineViolations = IViolation[];

package/types/cruise-result.d.ts

@@ -1,11 +1,8 @@
 import { ICruiseOptions } from "./options";
 import { IFlattenedRuleSet } from "./rule-set";
-import {
-  DependencyType,
-  ModuleSystemType,
-  SeverityType,
-  ProtocolType,
-} from "./shared-types";
+import { DependencyType, ModuleSystemType, ProtocolType } from "./shared-types";
+import { IViolation } from "./violations";
+import { IRuleSummary } from "./rule-summary";
 
 export interface ICruiseResult {
   /**
@@ -224,27 +221,11 @@ export interface IDependency {
    * will be in the 'rule' object at the same level.
    */
   valid: boolean;
-}
-
-/**
- * If there was a rule violation (valid === false), this object contains the name of the
- * rule and severity of violating it.
- */
-export interface IRuleSummary {
   /**
-   * The (short, eslint style) name of the violated rule. Typically something like
-   * 'no-core-punycode' or 'no-outside-deps'.
+   * the (de-normalized) instability of the dependency - also available in
+   * the module on the 'to' side of this dependency
    */
-  name: string;
-  /**
-   * How severe a violation of a rule is. The 'error' severity will make some reporters return
-   * a non-zero exit code, so if you want e.g. a build to stop when there's a rule violated:
-   * use that. The absence of the 'ignore' severity here is by design; ignored rules don't
-   * show up in the output.
-   *
-   * Severity to use when a dependency is not in the 'allowed' set of rules. Defaults to 'warn'
-   */
-  severity: SeverityType;
+  instability: number;
 }
 
 export interface IReachable {
@@ -389,29 +370,6 @@ export interface IWebpackConfig {
  */
 export type WebpackEnvType = { [key: string]: any } | string;
 
-export interface IViolation {
-  /**
-   * The violated rule
-   */
-  rule: IRuleSummary;
-  /**
-   * The from part of the dependency this violation is about
-   */
-  from: string;
-  /**
-   * The to part of the dependency this violation is about
-   */
-  to: string;
-  /**
-   * The circular path if the violation is about circularity
-   */
-  cycle?: string[];
-  /**
-   * The path from the from to the to if the violation is transitive
-   */
-  via?: string[];
-}
-
 export interface IFolder {
   /**
    * The name of the folder. FOlder names are normalized to posix (so
@@ -421,11 +379,11 @@ export interface IFolder {
   /**
    * List of folders depending on this folder
    */
-  dependents?: string[];
+  dependents?: { name: string }[];
   /**
    * List of folders this folder depends upon
    */
-  dependencies?: string[];
+  dependencies?: { name: string; instability: number }[];
   /**
    * The total number of modules detected in this folder and its sub-folders
    */
@@ -455,3 +413,6 @@ export interface IFolder {
    */
   instability?: number;
 }
+
+export * from "./violations";
+export * from "./rule-summary";

package/types/options.d.ts

@@ -239,4 +239,9 @@ export interface ICruiseOptions {
      */
     type: ProgressType;
   };
+  /**
+   * When this flag is set to true, dependency-cruiser will calculate (stability) metrics
+   * for all modules and folders. Defaults to false.
+   */
+  metrics?: boolean;
 }

package/types/reporter-options.d.ts

@@ -58,6 +58,12 @@ export interface IDotReporterOptions {
    * goal of the report)
    */
   filters?: IReporterFiltersType;
+  /**
+   * When passed the value 'true', shows instability metrics in the
+   * output if dependency-cruiser calculated them. Doesn't show them
+   * in all other cases. Defaults to false",
+   */
+  showMetrics?: boolean;
   /**
    * A bunch of criteria to (conditionally) theme the dot output
    */

package/types/restrictions.d.ts

@@ -92,6 +92,18 @@ export interface IToRestriction extends IBaseRestrictionType {
    * licenses. E.g. to flag everyting non MIT use "MIT" here
    */
   licenseNot?: string | string[];
+  /**
+   * When set to true moreUnstable matches for any dependency that has a higher
+   * Instability than the module that depends on it. When set to false it matches
+   * when the opposite is true; the dependency has an equal or lower Instability.
+   *
+   * This attribute is useful when you want to check against Robert C. Martin's
+   * stable dependency * principle. See online documentation for examples and
+   * details.
+   *
+   * Leave this out when you don't care either way.
+   */
+  moreUnstable?: boolean;
 }
 
 export interface IReachabilityToRestrictionType extends IBaseRestrictionType {

package/types/rule-summary.d.ts

@@ -0,0 +1,23 @@
+import { SeverityType } from "./shared-types";
+
+/**
+ * If there was a rule violation (valid === false), this object contains the name of the
+ * rule and severity of violating it.
+ */
+
+export interface IRuleSummary {
+  /**
+   * The (short, eslint style) name of the violated rule. Typically something like
+   * 'no-core-punycode' or 'no-outside-deps'.
+   */
+  name: string;
+  /**
+   * How severe a violation of a rule is. The 'error' severity will make some reporters return
+   * a non-zero exit code, so if you want e.g. a build to stop when there's a rule violated:
+   * use that. The absence of the 'ignore' severity here is by design; ignored rules don't
+   * show up in the output.
+   *
+   * Severity to use when a dependency is not in the 'allowed' set of rules. Defaults to 'warn'
+   */
+  severity: SeverityType;
+}

package/types/shared-types.d.ts

@@ -42,3 +42,10 @@ export type DependencyType =
   | "type-only";
 
 export type ProtocolType = "data:" | "file:" | "node:";
+
+export type ViolationType =
+  | "dependency"
+  | "module"
+  | "cycle"
+  | "reachability"
+  | "instability";

package/types/violations.d.ts

@@ -0,0 +1,43 @@
+import { IRuleSummary } from "./rule-summary";
+import { ViolationType } from "./shared-types";
+
+export interface IMetricsSummary {
+  from: {
+    instability: number;
+  };
+  to: {
+    instability: number;
+  };
+}
+
+export interface IViolation {
+  /**
+   * Type of violation. When left out assumed to be of type 'dependency'
+   */
+  type?: ViolationType;
+  /**
+   * The violated rule
+   */
+  rule: IRuleSummary;
+  /**
+   * The from part of the dependency this violation is about
+   */
+  from: string;
+  /**
+   * The to part of the dependency this violation is about
+   */
+  to: string;
+  /**
+   * The circular path if the violation is about circularity
+   */
+  cycle?: string[];
+  /**
+   * The path from the from to the to if the violation is transitive
+   */
+  via?: string[];
+  /**
+   * metrics - when the violation pertains to a violation of a metrics
+   * principle
+   */
+  metrics?: IMetricsSummary;
+}

package/src/enrich/derive/metrics/folder.js

@@ -1,9 +0,0 @@
-const getStabilityMetrics = require("./get-stability-metrics");
-const { shouldDeriveMetrics } = require("./utl");
-
-module.exports = function deriveMetrics(pModules, pOptions) {
-  if (shouldDeriveMetrics(pOptions)) {
-    return { folders: getStabilityMetrics(pModules) };
-  }
-  return {};
-};

package/src/enrich/derive/metrics/module-utl.js

@@ -1,27 +0,0 @@
-const path = require("path").posix;
-
-function getAfferentCouplings(pModule, pDirname) {
-  return pModule.dependents.filter(
-    (pDependent) => !pDependent.startsWith(pDirname.concat(path.sep))
-  );
-}
-
-function getEfferentCouplings(pModule, pDirname) {
-  return pModule.dependencies.filter(
-    (pDependency) => !pDependency.resolved.startsWith(pDirname.concat(path.sep))
-  );
-}
-
-function metricsAreCalculable(pModule) {
-  return (
-    !pModule.coreModule &&
-    !pModule.couldNotResolve &&
-    !pModule.matchesDoNotFollow
-  );
-}
-
-module.exports = {
-  getAfferentCouplings,
-  getEfferentCouplings,
-  metricsAreCalculable,
-};

package/src/enrich/derive/metrics/module.js

@@ -1,29 +0,0 @@
-// const { findModuleByName, clearCache } = require("../utl");
-const { metricsAreCalculable } = require("./module-utl");
-const { shouldDeriveMetrics } = require("./utl");
-
-module.exports = function deriveModuleMetrics(pModules, pOptions) {
-  if (shouldDeriveMetrics(pOptions)) {
-    return pModules.map((pModule) => ({
-      ...pModule,
-      ...(metricsAreCalculable(pModule)
-        ? {
-            instability:
-              pModule.dependencies.length /
-                (pModule.dependents.length + pModule.dependencies.length) || 0,
-          }
-        : {}),
-    }));
-    // clearCache();
-    // return lModules.map((pModule) => ({
-    //   ...pModule,
-    //   dependencies: pModule.dependencies.map((pDependency) => ({
-    //     ...pDependency,
-    //     instability:
-    //       (findModuleByName(lModules, pDependency.resolved) || {})
-    //         .instability || 0,
-    //   })),
-    // }));
-  }
-  return pModules;
-};

package/src/enrich/derive/metrics/utl.js

@@ -1,28 +0,0 @@
-/* eslint-disable security/detect-object-injection */
-function getParentFolders(pPath) {
-  let lFragments = pPath.split("/");
-  let lReturnValue = [];
-
-  while (lFragments.length > 0) {
-    lReturnValue.push(lFragments.join("/"));
-    lFragments.pop();
-  }
-  return lReturnValue.reverse();
-}
-
-function foldersObject2folderArray(pObject) {
-  return Object.keys(pObject).map((pKey) => ({
-    name: pKey,
-    ...pObject[pKey],
-  }));
-}
-
-function shouldDeriveMetrics(pOptions) {
-  return pOptions.metrics || pOptions.outputType === "metrics";
-}
-
-module.exports = {
-  getParentFolders,
-  foldersObject2folderArray,
-  shouldDeriveMetrics,
-};

package/src/validate/utl.js

@@ -1,31 +0,0 @@
-/**
- * If there is at least one group expression in the given pRulePath
- * return the first matched one.
- *
- * Return null in all other cases.
- *
- * This fills our current need. Later we can expand it to return all group
- * matches.
- *
- * @param {import("../../types/rule-set").IFromRestriction} pRestriction
- * @param {string} pActualPath
- * @returns {string[]|null}
- */
-function extractGroups(pRestriction, pActualPath) {
-  let lReturnValue = [];
-
-  if (Boolean(pRestriction.path)) {
-    let lMatchResult = pActualPath.match(pRestriction.path);
-
-    if (Boolean(lMatchResult) && lMatchResult.length > 1) {
-      lReturnValue = lMatchResult.filter(
-        (pResult) => typeof pResult === "string"
-      );
-    }
-  }
-  return lReturnValue;
-}
-
-module.exports = {
-  extractGroups,
-};