feature: adds reaches filter option

bin/depcruise-fmt.js

@@ -39,6 +39,10 @@ try {
       "-F, --focus <regex>",
       "only include modules matching the regex + their direct neighbours"
     )
+    .option(
+      "-R, --reaches <regex>",
+      "only include modules matching the regex + all modules that can reach it"
+    )
     .option("-x, --exclude <regex>", "exclude all modules matching the regex")
     .option(
       "-S, --collapse <regex>",

bin/dependency-cruise.js

@@ -42,6 +42,10 @@ try {
       "-F, --focus <regex>",
       "only include modules matching the regex + their direct neighbours"
     )
+    .option(
+      "-R, --reaches <regex>",
+      "only include modules matching the regex + all modules that can reach it"
+    )
     .option("-x, --exclude <regex>", "exclude all modules matching the regex")
     .option(
       "-X, --do-not-follow <regex>",

doc/cli.md

@@ -29,6 +29,7 @@ available in dependency-cruiser configurations.
 1. [`--do-not-follow`: don't cruise modules adhering to this pattern any further](#--do-not-follow-dont-cruise-modules-adhering-to-this-pattern-any-further)
 1. [`--include-only`: only include modules satisfying a pattern](#--include-only-only-include-modules-satisfying-a-pattern)
 1. [`--focus`: show modules and their direct neighbours](#--focus-show-modules-and-their-direct-neighbours)
+1. [`--reaches`: show modules and their transitive dependents](#--reaches-show-modules-and-their-transitive-dependents)
 1. [`--collapse`: summarize to folder depth or pattern](#--collapse-summarize-to-folder-depth-or-pattern)
 1. [`--exclude`: exclude dependencies from being cruised](#--exclude-exclude-dependencies-from-being-cruised)
 1. [`--max-depth`](#--max-depth)
@@ -858,12 +859,26 @@ Takes a regular expression in the same fashion `--include-only`, `--exclude` and
 `--do-not-follow` do.
 
 ```sh
-dependency-cruise --include-only "^src" --focus "^src/main" -T dot src | dot -T svg > focus-on-main-dir-graph.svg
+dependency-cruise src --include-only "^src" --focus "^src/main" -T dot | dot -T svg > focus-on-main-dir-graph.svg
 ```
 
 See [focus](./options-reference.md#show-modules-matching-a-pattern---with-their-direct-neighbours)
 in the options reference for more details.
 
+### `--reaches`: show modules and their transitive dependents
+
+If you want to e.g. analyze what modules will directly or indirectly be affected
+by a change you make in one or modules you can use this option.
+
+Just like the filter options above, takes a regular expression:
+
+```sh
+dependency-cruise src --include-only "^src/report" --reaches "^src/report/utl/index.js" -T dot | dot -T svg > reaches-example.svg
+```
+
+See [reaches](./options-reference.md#reaches-show-modules-matching-a-pattern---with-everything-that-can-reach-them)
+in the options reference for more details.
+
 ### `--collapse`: summarize to folder depth or pattern
 
 If you feel the need for reporting on a higher level (e.g. on packages in a

doc/options-reference.md

@@ -4,6 +4,7 @@
   - [`doNotFollow`: don't cruise modules any further](#donotfollow-dont-cruise-modules-any-further)
   - [`includeOnly`: only include modules satisfying a pattern](#includeonly-only-include-modules-satisfying-a-pattern)
   - [`focus`: show modules matching a pattern - with their direct neighbours](#focus-show-modules-matching-a-pattern---with-their-direct-neighbours)
+  - [`reaches`: show modules matching a pattern - with everything that can reach them](#reaches-show-modules-matching-a-pattern---with-everything-that-can-reach-them)
   - [`exclude`: exclude dependencies from being cruised](#exclude-exclude-dependencies-from-being-cruised)
   - [`collapse`: summarize to folder depth or pattern](#collapse-summarize-to-folder-depth-or-pattern)
   - [`maxDepth`](#maxdepth)
@@ -271,6 +272,37 @@ depcruise -c snazzy-focus.config.json -T dot | dot -T svg > snazzy-focus.svg
 
 </details>
 
+### `reaches`: show modules matching a pattern - with everything that can reach them
+
+> :shell: command line option equivalent: `--reaches`
+
+Just like the `includeOnly` and `focus` option, `reaches` takes a regular expression
+that dependency-cruiser uses to find modules to show in its output. In addition
+to what `includeOnly` does, dependency-cruiser will all dependents (direct _and_
+indirect) of the modules matched by the regular expression.
+
+This can be useful if you want to make an impact analysis on what would
+be affected when you change one or more modules around.
+
+Example configuration that'd filter out everything in src/report that can
+directly or indirectly reach the dependency-to-incidence-transformer module:
+
+```json
+{
+  "options": {
+    "includeOnly": "^src/report",
+    "reaches": "^src/report/utl/index.js"
+  }
+}
+```
+
+Which will look something like this when output through a `dot` reporter:
+
+![graphical output showing all modules in src/report that (transitively) depend on the src/report/utl/index.js module](assets/filtering/reaches-example.svg)
+
+> In later versions of dependency-cruiser 'snazzy' coloring options
+> might appear akin to those available with the 'focus' reporter.
+
 ### `exclude`: exclude dependencies from being cruised
 
 > :shell: command line option equivalent: `--exclude` (string values passed to 'path' only)

src/cli/normalize-cli-options.js

@@ -28,6 +28,7 @@ const KNOWN_DEPCRUISE_CLI_OPTIONS = [
   "prefix",
   "preserveSymlinks",
   "progress",
+  "reaches",
   "tsPreCompilationDeps",
   "tsConfig",
   "validate",

src/enrich/derive/dependents/index.js

@@ -10,10 +10,16 @@ function hasDependentsRule(pOptions) {
   );
 }
 
+/**
+ *
+ * @param {import("../../../../types/cruise-result").IOptions} pOptions
+ * @returns
+ */
 function shouldAddDependents(pOptions) {
   return (
     Boolean(pOptions.forceDeriveDependents) ||
     Boolean(pOptions.metrics) ||
+    Boolean(pOptions.reaches) ||
     pOptions.outputType === "metrics" ||
     hasDependentsRule(pOptions)
   );

src/enrich/derive/module-utl.js

@@ -1,3 +1,4 @@
+/** @type {Map<string,import('../../../types/cruise-result').IModule>} */
 let gIndexedGraph = null;
 
 /**

src/graph-utl/filterbank.js

@@ -1,5 +1,6 @@
 const clone = require("lodash/clone");
-const focus = require("./add-focus");
+const addFocus = require("./add-focus");
+const IndexedModuleGraph = require("./indexed-module-graph");
 const matchFacade = require("./match-facade");
 
 function includeOnly(pModules, pIncludeFilter) {
@@ -32,6 +33,37 @@ function exclude(pModules, pExcludeFilter) {
         }))
     : pModules;
 }
+/**
+ *
+ * @param {import("../../types/cruise-result").IModule[]} pModules
+ * @param {import("../../types/filter-types").IReachesType} pReachesFilter
+ * @returns {import("../../types/cruise-result").IModule[]}
+ */
+function filterReaches(pModules, pReachesFilter) {
+  const lModuleNamesToReach = pModules
+    .filter((pModule) =>
+      matchFacade.moduleMatchesFilter(pModule, pReachesFilter)
+    )
+    .map(({ source }) => source);
+
+  /** @type {Array<string>} */
+  let lReachingModules = [];
+  let lIndexedModules = new IndexedModuleGraph(pModules);
+
+  for (let lModuleToReach of lModuleNamesToReach) {
+    lReachingModules = lReachingModules.concat(
+      lIndexedModules.findTransitiveDependents(lModuleToReach)
+    );
+  }
+  return pModules
+    .filter(({ source }) => lReachingModules.includes(source))
+    .map((pModule) => ({
+      ...pModule,
+      dependencies: pModule.dependencies.filter(({ resolved }) =>
+        lReachingModules.includes(resolved)
+      ),
+    }));
+}
 
 function applyFilters(pModules, pFilters) {
   if (pFilters) {
@@ -44,7 +76,10 @@ function applyFilters(pModules, pFilters) {
       lReturnValue = includeOnly(lReturnValue, pFilters.includeOnly);
     }
     if (pFilters.focus) {
-      lReturnValue = focus(lReturnValue, pFilters.focus);
+      lReturnValue = addFocus(lReturnValue, pFilters.focus);
+    }
+    if (pFilters.reaches) {
+      lReturnValue = filterReaches(lReturnValue, pFilters.reaches);
     }
     return lReturnValue;
   }