document how to enforce max cycles

README.md

@@ -8,7 +8,7 @@ Circular dependencies are often a necessity in complex software, the presence of
 
 ```js
 // webpack.config.js
-let CircularDependencyPlugin = require('circular-dependency-plugin')
+const CircularDependencyPlugin = require('circular-dependency-plugin')
 
 module.exports = {
   entry: "./src/index",
@@ -27,19 +27,63 @@ module.exports = {
 
 ```js
 // webpack.config.js
-let CircularDependencyPlugin = require('circular-dependency-plugin')
+const CircularDependencyPlugin = require('circular-dependency-plugin')
 
 module.exports = {
   entry: "./src/index",
   plugins: [
     new CircularDependencyPlugin({
+      // `onStartDetecting` is called before the cycle detection starts
+      onStartDetecting({ compilation }) {
+        console.log('start detecting webpack modules cycles');
+      },
       // `onDetected` is called for each module that is cyclical
       onDetected({ module: webpackModuleRecord, paths, compilation }) {
         // `paths` will be an Array of the relative module paths that make up the cycle
         // `module` will be the module record generated by webpack that caused the cycle
         compilation.errors.push(new Error(paths.join(' -> ')))
-      }
+      },
+      // `onEndDetecting` is called before the cycle detection ends
+      onEndDetecting({ compilation }) {
+        console.log('end detecting webpack modules cycles');
+      },
     })
   ]
 }
 ```
+
+If you have some number of cycles and want to fail if any new ones are
+introduced, you can use the life cycle methods to count and fail when the
+count is exceeded. (Note if you care about detecting a cycle being replaced by
+another, this won't catch that.)
+
+```js
+// webpack.config.js
+const CircularDependencyPlugin = require('circular-dependency-plugin')
+
+const MAX_CYCLES = 5;
+let numCyclesDetected = 0;
+
+module.exports = {
+  entry: "./src/index",
+  plugins: [
+    new CircularDependencyPlugin({
+      onStartDetecting({ compilation }) {
+        numCyclesDetected = 0;
+      },
+      onDetected({ module: webpackModuleRecord, paths, compilation }) {
+        numCyclesDetected++;
+        compilation.warnings.push(new Error(paths.join(' -> ')))
+      },
+      onEndDetecting({ compilation }) {
+        if (numCyclesDetected > MAX_CYCLES) {
+          compilation.errors.push(new Error(
+            `Detected ${numCyclesDetected} cycles which exceeds configured limit of ${MAX_CYCLES}`
+          ));
+        }
+      },
+    })
+  ]
+}
+```
+```