dependency-cruiser 10.8.0-beta-1 → 11.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "10.8.0-beta-1",
+  "version": "11.0.0",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -131,13 +131,13 @@
     "version": "npm-run-all build depcruise:graph:doc scm:stage"
   },
   "dependencies": {
-    "acorn": "8.5.0",
+    "acorn": "8.6.0",
     "acorn-jsx": "5.3.2",
     "acorn-jsx-walk": "2.0.0",
     "acorn-loose": "8.2.1",
     "acorn-walk": "8.2.0",
-    "ajv": "8.6.3",
-    "chalk": "4.1.2",
+    "ajv": "8.8.2",
+    "chalk": "^4.1.2",
     "commander": "8.3.0",
     "enhanced-resolve": "5.8.3",
     "figures": "^3.2.0",
@@ -152,17 +152,17 @@
     "semver": "^7.3.5",
     "semver-try-require": "^5.0.1",
     "teamcity-service-messages": "0.1.11",
-    "tsconfig-paths-webpack-plugin": "3.5.1",
+    "tsconfig-paths-webpack-plugin": "3.5.2",
     "wrap-ansi": "^7.0.0"
   },
   "devDependencies": {
-    "@babel/core": "7.15.8",
-    "@babel/plugin-transform-modules-commonjs": "7.15.4",
-    "@babel/preset-typescript": "7.15.0",
-    "@swc/core": "1.2.105",
-    "@typescript-eslint/eslint-plugin": "5.2.0",
-    "@typescript-eslint/parser": "5.2.0",
-    "@vue/compiler-sfc": "3.2.20",
+    "@babel/core": "7.16.0",
+    "@babel/plugin-transform-modules-commonjs": "7.16.0",
+    "@babel/preset-typescript": "7.16.0",
+    "@swc/core": "1.2.113",
+    "@typescript-eslint/eslint-plugin": "5.4.0",
+    "@typescript-eslint/parser": "5.4.0",
+    "@vue/compiler-sfc": "3.2.23",
     "c8": "7.10.0",
     "chai": "4.3.4",
     "chai-json-schema": "1.5.1",
@@ -171,23 +171,23 @@
     "eslint-config-moving-meadow": "2.0.9",
     "eslint-config-prettier": "8.3.0",
     "eslint-plugin-budapestian": "3.0.1",
-    "eslint-plugin-import": "2.25.2",
+    "eslint-plugin-import": "2.25.3",
     "eslint-plugin-mocha": "9.0.0",
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-security": "1.4.0",
-    "eslint-plugin-unicorn": "37.0.1",
+    "eslint-plugin-unicorn": "39.0.0",
     "husky": "^4.3.8",
     "intercept-stdout": "0.1.2",
-    "lint-staged": "11.2.6",
+    "lint-staged": "12.1.2",
     "mocha": "9.1.3",
     "normalize-newline": "^3.0.0",
     "npm-run-all": "4.1.5",
-    "prettier": "2.4.1",
+    "prettier": "2.5.0",
     "proxyquire": "2.1.3",
     "shx": "0.3.3",
-    "svelte": "3.44.0",
+    "svelte": "3.44.2",
     "symlink-dir": "5.0.1",
-    "typescript": "4.4.4",
+    "typescript": "4.5.2",
     "upem": "^7.0.0",
     "vue-template-compiler": "2.6.14",
     "yarn": "1.22.17"
@@ -199,6 +199,11 @@
         "policy": "wanted",
         "because": "some eslint plugins (eslint-plugin-budapestian) are not compatible with eslint 8 yet "
       },
+      {
+        "package": "chalk",
+        "policy": "wanted",
+        "because": "version 5 only exports ejs - and we use cjs and don't transpile"
+      },
       {
         "package": "figures",
         "policy": "wanted",

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

@@ -0,0 +1,9 @@
+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.js

@@ -0,0 +1,29 @@
+// 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/{folders → metrics}/utl.js

@@ -17,7 +17,12 @@ function foldersObject2folderArray(pObject) {
   }));
 }
 
+function shouldDeriveMetrics(pOptions) {
+  return pOptions.metrics || pOptions.outputType === "metrics";
+}
+
 module.exports = {
   getParentFolders,
   foldersObject2folderArray,
+  shouldDeriveMetrics,
 };

package/src/enrich/derive/utl.js

@@ -1,14 +1,26 @@
-const _memoize = require("lodash/memoize");
+let gIndexedGraph = null;
 
-function bareFindModuleByName(pGraph, pSource) {
-  return pGraph.find((pNode) => pNode.source === pSource);
+/**
+ * Returns the module with attribute pSource, when it exists in the pModuleGraph.
+ * Returns undefined when it doesn't.
+ *
+ * This function uses an indexed cache for efficiency reasons. If you need to
+ * call this function consecutively for different module graphs, you can clear
+ * this cache with the clearCache function from this module.
+ *
+ * @param {import('../../../types/cruise-result').IModule[]} pModuleGraph
+ * @param {string} pSource
+ * @returns {import('../../../types/cruise-result').IModule | undefined}
+ */
+function findModuleByName(pModuleGraph, pSource) {
+  if (!gIndexedGraph) {
+    gIndexedGraph = new Map(
+      pModuleGraph.map((pModule) => [pModule.source, pModule])
+    );
+  }
+  return gIndexedGraph.get(pSource);
 }
 
-const findModuleByName = _memoize(
-  bareFindModuleByName,
-  (_pGraph, pSource) => pSource
-);
-
 function isDependent(pResolvedName) {
   return (pModule) =>
     pModule.dependencies.some(
@@ -17,7 +29,11 @@ function isDependent(pResolvedName) {
 }
 
 function clearCache() {
-  findModuleByName.cache.clear();
+  gIndexedGraph = null;
 }
 
-module.exports = { findModuleByName, clearCache, isDependent };
+module.exports = {
+  findModuleByName,
+  clearCache,
+  isDependent,
+};

package/src/enrich/enrich-modules.js

@@ -8,6 +8,7 @@ const addDependents = require("./derive/dependents");
 const deriveReachable = require("./derive/reachable");
 const addValidations = require("./add-validations");
 const softenKnownViolations = require("./soften-known-violations");
+const deriveModuleMetrics = require("./derive/metrics/module");
 
 module.exports = function enrichModules(pModules, pOptions) {
   bus.emit("progress", "analyzing: cycles", { level: busLogLevels.INFO });
@@ -18,6 +19,10 @@ module.exports = function enrichModules(pModules, pOptions) {
   lModules = deriveOrphans(lModules);
   bus.emit("progress", "analyzing: reachables", { level: busLogLevels.INFO });
   lModules = deriveReachable(lModules, pOptions.ruleSet);
+  bus.emit("progress", "analyzing: calculating module metrics", {
+    level: busLogLevels.INFO,
+  });
+  lModules = deriveModuleMetrics(lModules, pOptions);
   bus.emit("progress", "analyzing: add focus (if any)", {
     level: busLogLevels.INFO,
   });

package/src/enrich/index.js

@@ -1,5 +1,5 @@
 const enrichModules = require("./enrich-modules");
-const deriveFolders = require("./derive/folders");
+const deriveFolderMetrics = require("./derive/metrics/folder.js");
 const summarize = require("./summarize");
 const clearCaches = require("./clear-caches");
 
@@ -10,7 +10,7 @@ module.exports = function enrich(pModules, pOptions, pFileAndDirectoryArray) {
   clearCaches();
   return {
     modules: lModules,
-    ...deriveFolders(lModules, pOptions),
+    ...deriveFolderMetrics(lModules, pOptions),
     summary: summarize(lModules, pOptions, pFileAndDirectoryArray),
   };
 };

package/src/enrich/soften-known-violations.js

@@ -78,7 +78,8 @@ function softenKnownViolation(pModule, pKnownViolations, pSoftenedSeverity) {
           pRule,
           pModule.source,
           pKnownViolations.filter(
-            (pKnownError) => pKnownError.from === pKnownError.to
+            (pKnownError) =>
+              pKnownError.from === pKnownError.to && !pKnownError.cycle
           ),
           pSoftenedSeverity
         )
@@ -93,7 +94,8 @@ function softenKnownViolation(pModule, pKnownViolations, pSoftenedSeverity) {
         pDependency,
         pModule.source,
         pKnownViolations.filter(
-          (pKnownError) => pKnownError.from !== pKnownError.to
+          (pKnownError) =>
+            pKnownError.from !== pKnownError.to || pKnownError.cycle
         ),
         pSoftenedSeverity
       )

package/src/extract/ast-extractors/swc-dependency-visitor.js

@@ -119,7 +119,13 @@ if (VisitorModule) {
     // also include the same method, but with the correct spelling.
     visitExportAllDeclration(pNode) {
       this.pushImportExportSource(pNode);
-      return super.visitExportAllDeclration(pNode);
+      /* c8 ignore start */
+      if (super.visitExportAllDeclration) {
+        return super.visitExportAllDeclration(pNode);
+      } else {
+        /* c8 ignore stop */
+        return super.visitExportAllDeclaration(pNode);
+      }
     }
 
     /* c8 ignore start */
@@ -131,7 +137,13 @@ if (VisitorModule) {
     // same spelling error as the above - same solution
     visitExportNamedDeclration(pNode) {
       this.pushImportExportSource(pNode);
-      return super.visitExportNamedDeclration(pNode);
+      /* c8 ignore start */
+      if (super.visitExportNamedDeclration) {
+        return super.visitExportNamedDeclration(pNode);
+      } else {
+        /* c8 ignore stop */
+        return super.visitExportNamedDeclaration(pNode);
+      }
     }
     /* c8 ignore start */
     visitExportNamedDeclaration(pNode) {

package/src/extract/get-dependencies.js

@@ -21,15 +21,18 @@ function extractFromSwcAST(pOptions, pFileName) {
   );
 }
 
-function extractFromTypeScriptAST(pOptions, pFileName) {
+function extractFromTypeScriptAST(pOptions, pFileName, pTranspileOptions) {
   return extractTypeScriptDeps(
-    toTypescriptAST.getASTCached(path.join(pOptions.baseDir, pFileName)),
+    toTypescriptAST.getASTCached(
+      path.join(pOptions.baseDir, pFileName),
+      pTranspileOptions
+    ),
     pOptions.exoticRequireStrings
   );
 }
 
 function isTypeScriptCompatible(pFileName) {
-  return [".ts", ".tsx", ".js", ".mjs", ".cjs"].includes(
+  return [".ts", ".tsx", ".js", ".mjs", ".cjs", ".vue"].includes(
     path.extname(pFileName)
   );
 }
@@ -88,9 +91,11 @@ function extractWithTsc(
   pFileName,
   pTranspileOptions
 ) {
-  pDependencies = extractFromTypeScriptAST(pCruiseOptions, pFileName).filter(
-    (pDep) => pCruiseOptions.moduleSystems.includes(pDep.moduleSystem)
-  );
+  pDependencies = extractFromTypeScriptAST(
+    pCruiseOptions,
+    pFileName,
+    pTranspileOptions
+  ).filter((pDep) => pCruiseOptions.moduleSystems.includes(pDep.moduleSystem));
 
   if (pCruiseOptions.tsPreCompilationDeps === "specify") {
     pDependencies = detectPreCompilationNess(

package/src/extract/parse/to-typescript-ast.js

@@ -2,21 +2,28 @@ const fs = require("fs");
 const tryRequire = require("semver-try-require");
 const _memoize = require("lodash/memoize");
 const { supportedTranspilers } = require("../../../src/meta.js");
+const transpile = require("../transpile");
+const getExtension = require("../utl/get-extension");
 
 const typescript = tryRequire("typescript", supportedTranspilers.typescript);
 
 /**
  * Compiles pTypescriptSource into a (typescript) AST
  *
- * @param {string} pTypescriptSource - the source to compile
- * @param {string} [pFileName] - (optional) file name the typescript
- *                              compiler can use in error messages
+ * @param {object} pFileRecord Record with source code, an extension and a filename
+ * @param {any} [pTranspileOptions] options for the transpiler(s) - a tsconfig or
+ *                                a babel config
  * @return {object} - a (typescript) AST
  */
-function getASTFromSource(pTypescriptSource, pFileName) {
+function getASTFromSource(pFileRecord, pTranspileOptions) {
+  let lSource = pFileRecord.source;
+  if (pFileRecord.extension === ".vue") {
+    lSource = transpile(pFileRecord, pTranspileOptions);
+  }
+
   return typescript.createSourceFile(
-    pFileName || "$internal-file-name",
-    pTypescriptSource,
+    pFileRecord.filename || "$internal-file-name",
+    lSource,
     typescript.ScriptTarget.Latest,
     false
   );
@@ -27,10 +34,19 @@ function getASTFromSource(pTypescriptSource, pFileName) {
  * AST and returns it
  *
  * @param {string} pFileName - the name of the file to compile
+ * @param {any} [pTranspileOptions] options for the transpiler(s) - a tsconfig or
+ *                                a babel config
  * @return {object} - a (typescript) AST
  */
-function getAST(pFileName) {
-  return getASTFromSource(fs.readFileSync(pFileName, "utf8"), pFileName);
+function getAST(pFileName, pTranspileOptions) {
+  return getASTFromSource(
+    {
+      source: fs.readFileSync(pFileName, "utf8"),
+      extension: getExtension(pFileName),
+      filename: pFileName,
+    },
+    pTranspileOptions
+  );
 }
 
 const getASTCached = _memoize(getAST);

package/src/extract/utl/get-extension.js

@@ -5,16 +5,20 @@ const path = require("path");
  *
  * Just using path.extname would be fine for most cases,
  * except for coffeescript, where a markdown extension can
- * mean literate coffeescript.
+ * mean literate coffeescript, and for typescript where
+ * .d.ts and .ts are slightly different beasts
  *
  * @param {string} pFileName path to the file to be parsed
  * @return {string}          extension
  */
 module.exports = function getExtensions(pFileName) {
-  let lReturnValue = path.extname(pFileName);
+  if (pFileName.endsWith(".d.ts")) {
+    return ".d.ts";
+  }
 
-  if (lReturnValue === ".md") {
-    return pFileName.endsWith(".coffee.md") ? ".coffee.md" : lReturnValue;
+  if (pFileName.endsWith(".coffee.md")) {
+    return ".coffee.md";
   }
-  return lReturnValue;
+
+  return path.extname(pFileName);
 };

package/src/main/report-wrap.js

@@ -28,13 +28,18 @@ function reSummarizeResults(pResult, pFormatOptions) {
 
 module.exports = function reportWrap(pResult, pFormatOptions) {
   const lReportFunction = report.getReporter(pFormatOptions.outputType);
+  const lReportOptions = _get(
+    pResult,
+    `summary.optionsUsed.reporterOptions.${pFormatOptions.outputType}`,
+    {}
+  );
 
   return lReportFunction(
     reSummarizeResults(pResult, pFormatOptions),
     // passing format options here so reporters that read collapse patterns
     // from the result take the one passed in the format options instead
     _has(pFormatOptions, "collapse")
-      ? { collapsePattern: pFormatOptions.collapse }
-      : {}
+      ? { ...lReportOptions, collapsePattern: pFormatOptions.collapse }
+      : lReportOptions
   );
 };

package/src/meta.js

@@ -1,7 +1,7 @@
 /* generated - don't edit */
 
 module.exports = {
-  version: "10.8.0-beta-1",
+  version: "11.0.0",
   engines: {
     node: "^12.20||^14||>=16",
   },

package/src/report/metrics.js

@@ -1,62 +1,110 @@
-const os = require("os");
+const { EOL } = require("os");
 const chalk = require("chalk");
 
 const DECIMAL_BASE = 10;
 const METRIC_WIDTH = 4;
 const INSTABILITY_DECIMALS = 2;
 const YADDUM = DECIMAL_BASE ** INSTABILITY_DECIMALS;
+const COMPONENT_HEADER = "name";
 
-function transformMetricsToTable(pMetrics) {
+function getHeader(pMaxNameWidth) {
+  return `${COMPONENT_HEADER.padEnd(pMaxNameWidth)} ${"N".padStart(
+    METRIC_WIDTH + 1
+  )} ${"Ca".padStart(METRIC_WIDTH + 1)} ${"Ce".padStart(
+    METRIC_WIDTH + 1
+  )}  ${"I".padEnd(METRIC_WIDTH + 1)}`;
+}
+
+function getDemarcationLine(pMaxNameWidth) {
+  return `${"-".repeat(pMaxNameWidth)} ${"-".repeat(
+    METRIC_WIDTH + 1
+  )} ${"-".repeat(METRIC_WIDTH + 1)} ${"-".repeat(
+    METRIC_WIDTH + 1
+  )}  ${"-".repeat(METRIC_WIDTH + 1)}`;
+}
+
+function getMetricsTable(pMetrics, pMaxNameWidth) {
+  return pMetrics.map(
+    ({
+      name,
+      moduleCount,
+      afferentCouplings,
+      efferentCouplings,
+      instability,
+    }) =>
+      `${name.padEnd(pMaxNameWidth, " ")}  ${moduleCount
+        .toString(DECIMAL_BASE)
+        .padStart(METRIC_WIDTH)}  ${afferentCouplings
+        .toString(DECIMAL_BASE)
+        .padStart(METRIC_WIDTH)}  ${efferentCouplings
+        .toString(DECIMAL_BASE)
+        .padStart(METRIC_WIDTH)}  ${(Math.round(YADDUM * instability) / YADDUM)
+        .toString(DECIMAL_BASE)
+        .padEnd(METRIC_WIDTH)}`
+  );
+}
+
+function metricifyModule({ source, dependents, dependencies, instability }) {
+  return {
+    name: source,
+    moduleCount: 1,
+    afferentCouplings: dependents.length,
+    efferentCouplings: dependencies.length,
+    instability,
+  };
+}
+
+function metricsAreCalculable(pModule) {
+  return Object.prototype.hasOwnProperty.call(pModule, "instability");
+}
+
+function orderByNumber(pAttributeName) {
+  // eslint-disable-next-line security/detect-object-injection
+  return (pLeft, pRight) => pRight[pAttributeName] - pLeft[pAttributeName];
+}
+
+function orderByString(pAttributeName) {
+  return (pLeft, pRight) =>
+    // eslint-disable-next-line security/detect-object-injection
+    pLeft[pAttributeName].localeCompare(pRight[pAttributeName]);
+}
+
+function transformMetricsToTable(
+  { modules, folders },
+  { orderBy, hideFolders, hideModules }
+) {
   // TODO: should probably use a table module for this (i.e. text-table)
-  // to simplify this code; but for this poc not having a dependency (so it's
-  // copy-n-pasteable from a gist) is more important
-  const lMaxNameWidth = pMetrics
-    .map((pMetric) => pMetric.name.length)
+  // to simplify this code
+  let lComponents = [];
+  lComponents = lComponents.concat(hideFolders ? [] : folders);
+  lComponents = lComponents.concat(
+    hideModules ? [] : modules.filter(metricsAreCalculable).map(metricifyModule)
+  );
+  const lMaxNameWidth = lComponents
+    .map(({ name }) => name.length)
+    .concat(COMPONENT_HEADER.length)
     .sort((pLeft, pRight) => pLeft - pRight)
     .pop();
 
-  return [
-    chalk.bold(
-      `${"folder".padEnd(lMaxNameWidth)} ${"N".padStart(
-        METRIC_WIDTH + 1
-      )} ${"Ca".padStart(METRIC_WIDTH + 1)} ${"Ce".padStart(
-        METRIC_WIDTH + 1
-      )}  ${"I".padEnd(METRIC_WIDTH + 1)}`
-    ),
-  ]
-    .concat(
-      `${"-".repeat(lMaxNameWidth)} ${"-".repeat(
-        METRIC_WIDTH + 1
-      )} ${"-".repeat(METRIC_WIDTH + 1)} ${"-".repeat(
-        METRIC_WIDTH + 1
-      )}  ${"-".repeat(METRIC_WIDTH + 1)}`
-    )
+  return [chalk.bold(getHeader(lMaxNameWidth))]
+    .concat(getDemarcationLine(lMaxNameWidth))
     .concat(
-      pMetrics.map((pMetric) => {
-        return `${pMetric.name.padEnd(
-          lMaxNameWidth,
-          " "
-        )}  ${pMetric.moduleCount
-          .toString(DECIMAL_BASE)
-          .padStart(METRIC_WIDTH)}  ${pMetric.afferentCouplings
-          .toString(DECIMAL_BASE)
-          .padStart(METRIC_WIDTH)}  ${pMetric.efferentCouplings
-          .toString(DECIMAL_BASE)
-          .padStart(METRIC_WIDTH)}  ${(
-          Math.round(YADDUM * pMetric.instability) / YADDUM
-        )
-          .toString(DECIMAL_BASE)
-          .padEnd(METRIC_WIDTH)}`;
-      })
+      getMetricsTable(
+        lComponents
+          .sort(orderByString("name"))
+          .sort(orderByNumber(orderBy || "instability")),
+        lMaxNameWidth
+      )
     )
-    .join(os.EOL)
-    .concat(os.EOL);
+    .join(EOL)
+    .concat(EOL);
 }
 
 /**
- * Metrics plugin - to test the waters. If we want to use metrics in other
- * reporters - or use e.g. the Ca/ Ce/ I in rules (e.g. to detect violations
- * of Uncle Bob's variable dependency principle)
+ * returns stability metrics of modules & folders in an ascii table
+ *
+ * Potential future features:
+ * - additional output formats (csv?, html?)
  *
  * @param {import('../../types/dependency-cruiser').ICruiseResult} pCruiseResult -
  *      the output of a dependency-cruise adhering to dependency-cruiser's
@@ -65,17 +113,18 @@ function transformMetricsToTable(pMetrics) {
  *      output: some metrics on folders and dependencies
  *      exitCode: 0
  */
-module.exports = (pCruiseResult) => {
+module.exports = (pCruiseResult, pReporterOptions) => {
+  const lReporterOptions = pReporterOptions || {};
   if (pCruiseResult.folders) {
     return {
-      output: transformMetricsToTable(pCruiseResult.folders),
+      output: transformMetricsToTable(pCruiseResult, lReporterOptions),
       exitCode: 0,
     };
   } else {
     return {
       output:
-        `${os.EOL}ERROR: The cruise result didn't contain any metrics - re-running the cruise with${os.EOL}` +
-        `       the '--metrics' command line option should fix that.${os.EOL}${os.EOL}`,
+        `${EOL}ERROR: The cruise result didn't contain any metrics - re-running the cruise with${EOL}` +
+        `       the '--metrics' command line option should fix that.${EOL}${EOL}`,
       exitCode: 1,
     };
   }

package/src/schema/configuration.schema.js

@@ -394,6 +394,7 @@ module.exports = {
         dot: { $ref: "#/definitions/DotReporterOptionsType" },
         ddot: { $ref: "#/definitions/DotReporterOptionsType" },
         flat: { $ref: "#/definitions/DotReporterOptionsType" },
+        metrics: { $ref: "#/definitions/MetricsReporterOptionsType" },
       },
     },
     AnonReporterOptionsType: {
@@ -401,6 +402,24 @@ module.exports = {
       additionalProperties: false,
       properties: { wordlist: { type: "array", items: { type: "string" } } },
     },
+    MetricsReporterOptionsType: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        orderBy: {
+          type: "string",
+          enum: [
+            "instability",
+            "moduleCount",
+            "afferentCouplings",
+            "efferentCouplings",
+            "name",
+          ],
+        },
+        hideModules: { type: "boolean" },
+        hideFolders: { type: "boolean" },
+      },
+    },
     DotReporterOptionsType: {
       type: "object",
       additionalProperties: false,

package/src/schema/cruise-result.schema.js

@@ -47,6 +47,7 @@ module.exports = {
           items: { $ref: "#/definitions/RuleSummaryType" },
         },
         consolidated: { type: "boolean" },
+        instability: { type: "number" },
       },
     },
     ReachableType: {
@@ -570,6 +571,7 @@ module.exports = {
         dot: { $ref: "#/definitions/DotReporterOptionsType" },
         ddot: { $ref: "#/definitions/DotReporterOptionsType" },
         flat: { $ref: "#/definitions/DotReporterOptionsType" },
+        metrics: { $ref: "#/definitions/MetricsReporterOptionsType" },
       },
     },
     AnonReporterOptionsType: {
@@ -577,6 +579,24 @@ module.exports = {
       additionalProperties: false,
       properties: { wordlist: { type: "array", items: { type: "string" } } },
     },
+    MetricsReporterOptionsType: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        orderBy: {
+          type: "string",
+          enum: [
+            "instability",
+            "moduleCount",
+            "afferentCouplings",
+            "efferentCouplings",
+            "name",
+          ],
+        },
+        hideModules: { type: "boolean" },
+        hideFolders: { type: "boolean" },
+      },
+    },
     DotReporterOptionsType: {
       type: "object",
       additionalProperties: false,

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 {
   /**
@@ -106,6 +103,15 @@ export interface IModule {
    * purposes - it will not be present after a regular cruise.
    */
   consolidated?: boolean;
+  /**
+   * "number of dependents/ (number of dependents + number of dependencies)
+   * A measure for how stable the module is; ranging between 0 (completely
+   * stable module) to 1 (completely instable module). Derived from Uncle
+   * Bob's instability metric - but applied to a single module instead of
+   * to a group of them. This attribute is only present when dependency-cruiser
+   * was asked to calculate metrics.
+   */
+  instability?: number;
 }
 
 export interface IDependency {
@@ -217,27 +223,6 @@ export interface IDependency {
   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'.
-   */
-  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;
-}
-
 export interface IReachable {
   /**
    * The name of the rule where the reachability was defined
@@ -380,29 +365,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
@@ -446,3 +408,6 @@ export interface IFolder {
    */
   instability?: number;
 }
+
+export * from "./violations";
+export * from "./rule-summary";

package/types/reporter-options.d.ts

@@ -21,6 +21,10 @@ export interface IReporterOptions {
    * Options to tweak the output of the flat /fdot reporter
    */
   flat?: IDotReporterOptions;
+  /**
+   * Options to tweak the output of the metrics reporter
+   */
+  metrics?: IMetricsReporterOptions;
 }
 
 export interface IReporterFiltersType {
@@ -96,3 +100,16 @@ export interface IDotThemeEntry {
   criteria: any;
   attributes: any;
 }
+
+export interface IMetricsReporterOptions {
+  hideModules?: boolean;
+  hideFolders?: boolean;
+  oderBy?: MetricsOrderByType;
+}
+
+export type MetricsOrderByType =
+  | "instability"
+  | "moduleCount"
+  | "afferentCouplings"
+  | "efferentCouplings"
+  | "name";

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/violations.d.ts

@@ -0,0 +1,24 @@
+import { IRuleSummary } from "./rule-summary";
+
+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[];
+}

package/src/enrich/derive/folders/index.js

@@ -1,12 +0,0 @@
-const getStabilityMetrics = require("./get-stability-metrics");
-
-function shouldDeriveFolders(pOptions) {
-  return pOptions.metrics || pOptions.outputType === "metrics";
-}
-
-module.exports = function deriveFolders(pModules, pOptions) {
-  if (shouldDeriveFolders(pOptions)) {
-    return { folders: getStabilityMetrics(pModules) };
-  }
-  return {};
-};