dependency-cruiser 10.5.0 → 10.8.0-beta-2

package/bin/dependency-cruise.js

@@ -28,6 +28,7 @@ try {
       "-T, --output-type <type>",
       "output type; e.g. err, err-html, dot, ddot, archi, flat, baseline or json\n(default: err)"
     )
+    .option("-m, --metrics", "calculate stability metrics", false)
     .option(
       "-f, --output-to <file>",
       "file to write output to; - for stdout",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-cruiser",
-  "version": "10.5.0",
+  "version": "10.8.0-beta-2",
   "description": "Validate and visualize dependencies. With your rules. JavaScript, TypeScript, CoffeeScript. ES6, CommonJS, AMD.",
   "keywords": [
     "static analysis",
@@ -138,7 +138,7 @@
     "acorn-walk": "8.2.0",
     "ajv": "8.6.3",
     "chalk": "4.1.2",
-    "commander": "8.2.0",
+    "commander": "8.3.0",
     "enhanced-resolve": "5.8.3",
     "figures": "^3.2.0",
     "get-stream": "^6.0.1",
@@ -159,9 +159,10 @@
     "@babel/core": "7.15.8",
     "@babel/plugin-transform-modules-commonjs": "7.15.4",
     "@babel/preset-typescript": "7.15.0",
-    "@swc/core": "1.2.98",
-    "@typescript-eslint/eslint-plugin": "5.0.0",
-    "@typescript-eslint/parser": "5.0.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",
     "c8": "7.10.0",
     "chai": "4.3.4",
     "chai-json-schema": "1.5.1",
@@ -169,7 +170,7 @@
     "eslint": "^7.32.0",
     "eslint-config-moving-meadow": "2.0.9",
     "eslint-config-prettier": "8.3.0",
-    "eslint-plugin-budapestian": "2.3.0",
+    "eslint-plugin-budapestian": "3.0.1",
     "eslint-plugin-import": "2.25.2",
     "eslint-plugin-mocha": "9.0.0",
     "eslint-plugin-node": "11.1.0",
@@ -177,13 +178,14 @@
     "eslint-plugin-unicorn": "37.0.1",
     "husky": "^4.3.8",
     "intercept-stdout": "0.1.2",
-    "lint-staged": "11.2.3",
+    "lint-staged": "11.2.6",
     "mocha": "9.1.3",
-    "normalize-newline": "4.1.0",
+    "normalize-newline": "^3.0.0",
     "npm-run-all": "4.1.5",
     "prettier": "2.4.1",
+    "proxyquire": "2.1.3",
     "shx": "0.3.3",
-    "svelte": "3.43.2",
+    "svelte": "3.44.0",
     "symlink-dir": "5.0.1",
     "typescript": "4.4.4",
     "upem": "^7.0.0",
@@ -212,6 +214,11 @@
         "policy": "wanted",
         "because": "version 5 only exports ejs - and we use cjs and don't transpile"
       },
+      {
+        "package": "normalize-newline",
+        "policy": "wanted",
+        "because": "version 4 only exports ejs - and we use cjs and don't transpile (this only used in unit tests - but one of'em is a cjs one ...)"
+      },
       {
         "package": "wrap-ansi",
         "policy": "wanted",
@@ -246,7 +253,8 @@
     "svelte": ">=3.0.0 <4.0.0",
     "swc": ">=1.0.0 <2.0.0",
     "typescript": ">=2.0.0 <5.0.0",
-    "vue-template-compiler": ">=2.0.0 <3.0.0"
+    "vue-template-compiler": ">=2.0.0 <3.0.0",
+    "@vue/compiler-sfc": ">=3.0.0 <4.0.0"
   },
   "husky": {
     "hooks": {

package/src/cli/normalize-cli-options.js

@@ -21,6 +21,7 @@ const KNOWN_DEPCRUISE_CLI_OPTIONS = [
   "info",
   "init",
   "maxDepth",
+  "metrics",
   "moduleSystems",
   "outputTo",
   "outputType",

package/src/cli/validate-node-environment.js

@@ -5,7 +5,7 @@ module.exports = function validateNodeEnvironment(pNodeVersion) {
   // not using default parameter here because the check should run
   // run on node 4 as well
   const lNodeVersion = pNodeVersion || process.versions.node;
-  const VERSION_ERR = `\nERROR: Your node version (${lNodeVersion}) is not supported. dependency-cruiser
+  const lVersionError = `\nERROR: Your node version (${lNodeVersion}) is not supported. dependency-cruiser
        follows the node.js release cycle and runs on these node versions:
        ${engines.node}
        See https://nodejs.org/en/about/releases/ for details.
@@ -13,6 +13,6 @@ module.exports = function validateNodeEnvironment(pNodeVersion) {
 `;
 
   if (!satisfies(lNodeVersion, engines.node)) {
-    throw new Error(VERSION_ERR);
+    throw new Error(lVersionError);
   }
 };

package/src/enrich/add-validations.js

@@ -20,11 +20,12 @@ function addDependencyViolations(pModule, pDependency, pRuleSet, pValidate) {
  *                  of them added whether or not it is
  *                  valid and if not which rules were violated
  */
-module.exports = (pModules, pRuleSet, pValidate) =>
-  pModules.map((pModule) => ({
+module.exports = (pModules, pRuleSet, pValidate) => {
+  return pModules.map((pModule) => ({
     ...pModule,
     ...(pValidate ? validate.module(pRuleSet, pModule) : { valid: true }),
     dependencies: pModule.dependencies.map((pDependency) =>
       addDependencyViolations(pModule, pDependency, pRuleSet, pValidate)
     ),
   }));
+};

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

@@ -11,7 +11,12 @@ function hasDependentsRule(pOptions) {
 }
 
 function shouldAddDependents(pOptions) {
-  return Boolean(pOptions.forceDeriveDependents) || hasDependentsRule(pOptions);
+  return (
+    Boolean(pOptions.forceDeriveDependents) ||
+    Boolean(pOptions.metrics) ||
+    pOptions.outputType === "metrics" ||
+    hasDependentsRule(pOptions)
+  );
 }
 
 module.exports = function addDependents(pModules, pOptions) {

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/get-stability-metrics.js

@@ -0,0 +1,97 @@
+/* eslint-disable security/detect-object-injection */
+const path = require("path").posix;
+const { foldersObject2folderArray, getParentFolders } = require("./utl");
+const {
+  getAfferentCouplings,
+  getEfferentCouplings,
+  metricsAreCalculable,
+} = require("./module-utl");
+
+function upsertCouplings(pAllDependents, pNewDependents) {
+  pNewDependents.forEach((pNewDependent) => {
+    pAllDependents[pNewDependent] = pAllDependents[pNewDependent] || {
+      count: 0,
+    };
+    pAllDependents[pNewDependent].count += 1;
+  });
+}
+
+function upsertFolderAttributes(pAllMetrics, pModule, pDirname) {
+  pAllMetrics[pDirname] = pAllMetrics[pDirname] || {
+    dependencies: {},
+    dependents: {},
+    moduleCount: 0,
+  };
+
+  upsertCouplings(
+    pAllMetrics[pDirname].dependents,
+    getAfferentCouplings(pModule, pDirname)
+  );
+  upsertCouplings(
+    pAllMetrics[pDirname].dependencies,
+    getEfferentCouplings(pModule, pDirname).map(
+      (pDependency) => pDependency.resolved
+    )
+  );
+  pAllMetrics[pDirname].moduleCount += 1;
+
+  return pAllMetrics;
+}
+
+function orderFolderMetrics(pLeftMetric, pRightMetric) {
+  // return pLeft.name.localeCompare(pRight.name);
+  // For intended use in a table it's probably more useful to sort by
+  // instability. Might need to be either configurable or flexible
+  // in the output, though
+  return pRightMetric.instability - pLeftMetric.instability;
+}
+
+function sumCounts(pAll, pCurrent) {
+  return pAll + pCurrent.count;
+}
+
+function getFolderLevelCouplings(pCouplingArray) {
+  return Array.from(
+    new Set(
+      pCouplingArray.map((pCoupling) =>
+        path.dirname(pCoupling.name) === "."
+          ? pCoupling.name
+          : path.dirname(pCoupling.name)
+      )
+    )
+  );
+}
+
+function calculateFolderMetrics(pFolder) {
+  const lModuleDependents = foldersObject2folderArray(pFolder.dependents);
+  const lModuleDependencies = foldersObject2folderArray(pFolder.dependencies);
+  const lAfferentCouplings = lModuleDependents.reduce(sumCounts, 0);
+  const lEfferentCouplings = lModuleDependencies.reduce(sumCounts, 0);
+
+  return {
+    ...pFolder,
+    afferentCouplings: lAfferentCouplings,
+    efferentCouplings: lEfferentCouplings,
+    // when both afferentCouplings and efferentCouplings equal 0 instability will
+    // yield NaN. Judging Bob Martin's intention, a component with no outgoing
+    // dependencies is maximum stable (0)
+    instability:
+      lEfferentCouplings / (lEfferentCouplings + lAfferentCouplings) || 0,
+    dependents: getFolderLevelCouplings(lModuleDependents),
+    dependencies: getFolderLevelCouplings(lModuleDependencies),
+  };
+}
+
+module.exports = function getStabilityMetrics(pModules) {
+  return foldersObject2folderArray(
+    pModules.filter(metricsAreCalculable).reduce((pAllFolders, pModule) => {
+      getParentFolders(path.dirname(pModule.source)).forEach(
+        (pParentDirectory) =>
+          upsertFolderAttributes(pAllFolders, pModule, pParentDirectory)
+      );
+      return pAllFolders;
+    }, {})
+  )
+    .map(calculateFolderMetrics)
+    .sort(orderFolderMetrics);
+};

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

@@ -0,0 +1,27 @@
+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

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

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

@@ -0,0 +1,28 @@
+/* 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/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,4 +1,5 @@
 const enrichModules = require("./enrich-modules");
+const deriveFolderMetrics = require("./derive/metrics/folder.js");
 const summarize = require("./summarize");
 const clearCaches = require("./clear-caches");
 
@@ -9,6 +10,7 @@ module.exports = function enrich(pModules, pOptions, pFileAndDirectoryArray) {
   clearCaches();
   return {
     modules: lModules,
+    ...deriveFolderMetrics(lModules, pOptions),
     summary: summarize(lModules, pOptions, pFileAndDirectoryArray),
   };
 };

package/src/extract/transpile/meta.js

@@ -39,6 +39,7 @@ const TRANSPILER2WRAPPER = {
   swc,
   typescript: typeScriptWrap,
   "vue-template-compiler": vueWrap,
+  "@vue/compiler-sfc": vueWrap,
 };
 
 const BABELEABLE_EXTENSIONS = [

package/src/extract/transpile/vue-template-wrap.js

@@ -1,15 +1,58 @@
+const isEmpty = require("lodash/isEmpty");
 const _get = require("lodash/get");
 const tryRequire = require("semver-try-require");
 const { supportedTranspilers } = require("../../../src/meta.js");
 
-const vueTemplateCompiler = tryRequire(
-  "vue-template-compiler",
-  supportedTranspilers["vue-template-compiler"]
-);
+/*
+ * vue-template-compiler was replaced by @vue/compiler-sfc for Vue3.
+ *
+ * if your project uses Vue3, then trying to require vue-template-compiler will
+ * cause an incompatibility error - so try @vue/compiler-sfc (which is Vue3's
+ * version of vue-template-compiler) if the first one fails
+ */
+function getVueTemplateCompiler() {
+  let lIsVue3 = false;
+
+  let lCompiler = tryRequire(
+    "vue-template-compiler",
+    supportedTranspilers["vue-template-compiler"]
+  );
+
+  if (lCompiler === false) {
+    lCompiler = tryRequire(
+      "@vue/compiler-sfc",
+      supportedTranspilers["@vue/compiler-sfc"]
+    );
+    lIsVue3 = true;
+  }
+
+  return { lCompiler, lIsVue3 };
+}
+
+const { lCompiler: vueTemplateCompiler, lIsVue3: isVue3 } =
+  getVueTemplateCompiler();
+
+function vue3Transpile(pSource) {
+  const parsedComponent = vueTemplateCompiler.parse(pSource);
+  const errors = _get(parsedComponent, "errors");
+
+  if (!isEmpty(errors)) {
+    return "";
+  }
+
+  return _get(parsedComponent, "descriptor.script.content", "");
+}
+
+function vue2Transpile(pSource) {
+  return _get(
+    vueTemplateCompiler.parseComponent(pSource),
+    "script.content",
+    ""
+  );
+}
 
 module.exports = {
   isAvailable: () => vueTemplateCompiler !== false,
-
   transpile: (pSource) =>
-    _get(vueTemplateCompiler.parseComponent(pSource), "script.content", ""),
+    isVue3 ? vue3Transpile(pSource) : vue2Transpile(pSource),
 };

package/src/main/options/normalize.js

@@ -54,12 +54,12 @@ function normalizeFilterOptions(pOptions, pFilterOptionKeys) {
 function normalizeCollapse(pCollapse) {
   let lReturnValue = pCollapse;
   const lOneOrMoreNonSlashes = "[^/]+";
-  const FOLDER_PATTERN = `${lOneOrMoreNonSlashes}/`;
-  const FOLDER_BELOW_NODE_MODULES = `node_modules/${lOneOrMoreNonSlashes}`;
+  const lFolderPattern = `${lOneOrMoreNonSlashes}/`;
+  const lFolderBelowNodeModules = `node_modules/${lOneOrMoreNonSlashes}`;
   const lSingleDigitRe = /^\d$/;
 
   if (typeof pCollapse === "number" || pCollapse.match(lSingleDigitRe)) {
-    lReturnValue = `${FOLDER_BELOW_NODE_MODULES}|^${FOLDER_PATTERN.repeat(
+    lReturnValue = `${lFolderBelowNodeModules}|^${lFolderPattern.repeat(
       Number.parseInt(pCollapse, 10)
     )}`;
   }

package/src/meta.js

@@ -1,7 +1,7 @@
 /* generated - don't edit */
 
 module.exports = {
-  version: "10.5.0",
+  version: "10.8.0-beta-2",
   engines: {
     node: "^12.20||^14||>=16",
   },
@@ -14,5 +14,6 @@ module.exports = {
     swc: ">=1.0.0 <2.0.0",
     typescript: ">=2.0.0 <5.0.0",
     "vue-template-compiler": ">=2.0.0 <3.0.0",
+    "@vue/compiler-sfc": ">=3.0.0 <4.0.0",
   },
 };

package/src/report/index.js

@@ -13,6 +13,7 @@ const json = require("./json");
 const teamcity = require("./teamcity");
 const text = require("./text");
 const baseline = require("./baseline");
+const metrics = require("./metrics");
 const { getExternalPluginReporter } = require("./plugins");
 
 const TYPE2REPORTER = {
@@ -32,6 +33,7 @@ const TYPE2REPORTER = {
   teamcity,
   text,
   baseline,
+  metrics,
 };
 
 /**

package/src/report/metrics.js

@@ -0,0 +1,113 @@
+const os = 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 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((pMetric) => {
+    return `${pMetric.name.padEnd(pMaxNameWidth, " ")}  ${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)}`;
+  });
+}
+
+function metricifyModule({ source, dependents, dependencies, instability }) {
+  return {
+    name: source,
+    moduleCount: 1,
+    afferentCouplings: dependents.length,
+    efferentCouplings: dependencies.length,
+    instability,
+  };
+}
+
+function metricsAreCalculable(pModule) {
+  return (
+    !pModule.coreModule &&
+    !pModule.couldNotResolve &&
+    !pModule.matchesDoNotFollow
+  );
+}
+
+function orderByInstability(pLeft, pRight) {
+  return pRight.instability - pLeft.instability;
+}
+function transformMetricsToTable({ modules, folders }) {
+  // TODO: should probably use a table module for this (i.e. text-table)
+  // to simplify this code
+  const lMaxNameWidth = folders
+    .map((pFolder) => pFolder.name.length)
+    .concat(modules.map((pModule) => pModule.source.length))
+    .concat(COMPONENT_HEADER.length)
+    .sort((pLeft, pRight) => pLeft - pRight)
+    .pop();
+
+  return [chalk.bold(getHeader(lMaxNameWidth))]
+    .concat(getDemarcationLine(lMaxNameWidth))
+    .concat(
+      getMetricsTable(
+        folders
+          .concat(modules.filter(metricsAreCalculable).map(metricifyModule))
+          .sort(orderByInstability),
+        lMaxNameWidth
+      )
+    )
+    .join(os.EOL)
+    .concat(os.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)
+ *
+ * @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 metrics on folders and dependencies
+ *      exitCode: 0
+ */
+module.exports = (pCruiseResult) => {
+  if (pCruiseResult.folders) {
+    return {
+      output: transformMetricsToTable(pCruiseResult),
+      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}`,
+      exitCode: 1,
+    };
+  }
+};

package/src/report/teamcity.js

@@ -45,10 +45,26 @@ function reportAllowedRule(pAllowedRule, pViolations) {
   return lReturnValue;
 }
 
-function reportViolatedRules(pRuleSetUsed, pViolations) {
+function reportIgnoredRules(pIgnoredCount) {
+  let lReturnValue = [];
+
+  if (pIgnoredCount > 0) {
+    lReturnValue = tsm.inspectionType({
+      id: "ignored-known-violations",
+      name: "ignored-known-violations",
+      description:
+        "some dependency violations were ignored; run without --ignore-known to see them",
+      category: CATEGORY,
+    });
+  }
+  return lReturnValue;
+}
+
+function reportViolatedRules(pRuleSetUsed, pViolations, pIgnoredCount) {
   return reportRules(_get(pRuleSetUsed, "forbidden", []), pViolations)
     .concat(reportAllowedRule(_get(pRuleSetUsed, "allowed", []), pViolations))
-    .concat(reportRules(_get(pRuleSetUsed, "required", []), pViolations));
+    .concat(reportRules(_get(pRuleSetUsed, "required", []), pViolations))
+    .concat(reportIgnoredRules(pIgnoredCount));
 }
 
 function determineTo(pViolation) {
@@ -66,15 +82,31 @@ function bakeViolationMessage(pViolation) {
     ? pViolation.from
     : `${pViolation.from} -> ${determineTo(pViolation)}`;
 }
-function reportViolations(pViolations) {
-  return pViolations.map((pViolation) =>
-    tsm.inspection({
-      typeId: pViolation.rule.name,
-      message: bakeViolationMessage(pViolation),
-      file: pViolation.from,
-      SEVERITY: severity2teamcitySeverity(pViolation.rule.severity),
-    })
-  );
+
+function reportIgnoredViolation(pIgnoredCount) {
+  let lReturnValue = [];
+
+  if (pIgnoredCount > 0) {
+    lReturnValue = tsm.inspection({
+      typeId: "ignored-known-violations",
+      message: `${pIgnoredCount} known violations ignored. Run without --ignore-known to see them.`,
+      SEVERITY: "WARNING",
+    });
+  }
+  return lReturnValue;
+}
+
+function reportViolations(pViolations, pIgnoredCount) {
+  return pViolations
+    .map((pViolation) =>
+      tsm.inspection({
+        typeId: pViolation.rule.name,
+        message: bakeViolationMessage(pViolation),
+        file: pViolation.from,
+        SEVERITY: severity2teamcitySeverity(pViolation.rule.severity),
+      })
+    )
+    .concat(reportIgnoredViolation(pIgnoredCount));
 }
 
 /**
@@ -96,11 +128,14 @@ module.exports = (pResults) => {
   tsm.stdout = false;
 
   const lRuleSet = _get(pResults, "summary.ruleSetUsed", []);
-  const lViolations = _get(pResults, "summary.violations", []);
+  const lViolations = _get(pResults, "summary.violations", []).filter(
+    (pViolation) => pViolation.rule.severity !== "ignore"
+  );
+  const lIgnoredCount = _get(pResults, "summary.ignore", 0);
 
   return {
-    output: reportViolatedRules(lRuleSet, lViolations)
-      .concat(reportViolations(lViolations))
+    output: reportViolatedRules(lRuleSet, lViolations, lIgnoredCount)
+      .concat(reportViolations(lViolations, lIgnoredCount))
       .reduce((pAll, pCurrent) => `${pAll}${pCurrent}\n`, ""),
     exitCode: pResults.summary.error,
   };

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

@@ -9,6 +9,7 @@ module.exports = {
   additionalProperties: false,
   properties: {
     modules: { $ref: "#/definitions/ModulesType" },
+    folders: { $ref: "#/definitions/FoldersType" },
     summary: { $ref: "#/definitions/SummaryType" },
   },
   definitions: {
@@ -46,6 +47,7 @@ module.exports = {
           items: { $ref: "#/definitions/RuleSummaryType" },
         },
         consolidated: { type: "boolean" },
+        instability: { type: "number" },
       },
     },
     ReachableType: {
@@ -158,6 +160,21 @@ module.exports = {
       },
     },
     SeverityType: { type: "string", enum: ["error", "warn", "info", "ignore"] },
+    FoldersType: { type: "array", items: { $ref: "#/definitions/FolderType" } },
+    FolderType: {
+      type: "object",
+      required: ["name", "moduleCount"],
+      additionalProperties: false,
+      properties: {
+        name: { type: "string" },
+        dependents: { type: "array", items: { type: "string" } },
+        dependencies: { type: "array", items: { type: "string" } },
+        moduleCount: { type: "number" },
+        afferentCouplings: { type: "number" },
+        efferentCouplings: { type: "number" },
+        instability: { type: "number" },
+      },
+    },
     SummaryType: {
       type: "object",
       required: [
@@ -510,6 +527,7 @@ module.exports = {
             "teamcity",
             "anon",
             "text",
+            "metrics",
           ],
         },
         { type: "string", pattern: "^plugin:[^:]+$" },

package/src/utl/wrap-and-indent.js

@@ -4,7 +4,7 @@ const wrapAnsi = require("wrap-ansi");
 const DEFAULT_INDENT = 4;
 module.exports = function wrapAndIndent(pString, pIndent = DEFAULT_INDENT) {
   const lDogmaticMaxConsoleWidth = 78;
-  const MAX_WIDTH = lDogmaticMaxConsoleWidth - pIndent;
+  const lMaxWidth = lDogmaticMaxConsoleWidth - pIndent;
 
-  return indentString(wrapAnsi(pString, MAX_WIDTH), pIndent);
+  return indentString(wrapAnsi(pString, lMaxWidth), pIndent);
 };

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

@@ -52,6 +52,7 @@ function match(pFrom, pTo) {
     );
   };
 }
+
 const isInteresting = (pRule) => !isModuleOnlyRule(pRule);
 
 module.exports = {

package/types/cruise-result.d.ts

@@ -12,6 +12,15 @@ export interface ICruiseResult {
    * A list of modules, with for each module the modules it depends upon
    */
   modules: IModule[];
+  /**
+   * A list of folders, as derived from the detected modules, with for each
+   * "folder a bunch of metrics (adapted from 'Agile software development:
+   * "principles, patterns, and practices' by Robert C Martin (ISBN 0-13-597444-5).
+   * "Note: these metrics substitute 'components' and 'classes' from that book
+   * "with 'folders' and 'modules'; the closest relatives that work for the most
+   * "programming styles in JavaScript (and its derivative languages).
+   */
+  folders?: IFolder[];
   /**
    * Data summarizing the found dependencies
    */
@@ -97,6 +106,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 {
@@ -393,3 +411,47 @@ export interface IViolation {
    */
   via?: string[];
 }
+
+export interface IFolder {
+  /**
+   * The name of the folder. FOlder names are normalized to posix (so
+   * separated by forward slashes e.g.: src/things/morethings)
+   */
+  name: string;
+  /**
+   * List of folders depending on this folder
+   */
+  dependents?: string[];
+  /**
+   * List of folders this folder depends upon
+   */
+  dependencies?: string[];
+  /**
+   * The total number of modules detected in this folder and its sub-folders
+   */
+  moduleCount: number;
+  /**
+   * The number of modules outside this folder that depend on modules
+   * within this folder. Only present when dependency-cruiser was
+   * "asked to calculate it.
+   */
+  afferentCouplings?: number;
+  /**
+   * The number of modules inside this folder that depend on modules
+   * outside this folder. Only present when dependency-cruiser was
+   * asked to calculate it.
+   */
+  efferentCouplings?: number;
+  /**
+   * efferentCouplings/ (afferentCouplings + efferentCouplings)
+   *
+   * A measure for how stable the folder is; ranging between 0
+   * (completely stable folder) to 1 (completely instable folder)
+   * Note that while 'instability' has a negative connotation it's also
+   * (unavoidable in any meaningful system. It's the basis of Martin's
+   * variable component stability principle: 'the instability of a folder
+   * should be larger than the folders it depends on'. Only present when
+   * dependency-cruiser was asked to calculate it.,
+   */
+  instability?: number;
+}

package/types/shared-types.d.ts

@@ -18,6 +18,7 @@ export type OutputType =
   | "teamcity"
   | "anon"
   | "text"
+  | "metrics"
   | string;
 
 export type SeverityType = "error" | "warn" | "info" | "ignore";