feat(cli): adds 'affected' option (#952)

## Description

- adds an `--affected` option
- 🏕️ drive-by: sets the timeout for mocha tests higher so the ci doesn't
barf on windows

## Motivation and Context

I'm using `--reaches $(watskeburt main)` reasonably often lately;
`--affected` is a shortcut for that, assuming it'll be useful for other
folks as well.

## How Has This Been Tested?

- [x] green ci

## Types of changes

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Documentation only change
- [ ] Refactor (non-breaking change which fixes an issue without
changing functionality)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)

.mocharc.cjs

@@ -3,6 +3,6 @@
 module.exports = {
  extension: ["js", "mjs", "cjs"],
  reporter: "dot",
- timeout: 4000,
+ timeout: 8000, // 8s for testing on windows - with the previous setting of 4s it regularly timed out on the "uses the 'dot' reporter section for the 'x-dot-webpage' output type" test in main.format
  spec: "test/**/*.spec.{js,mjs,cjs}",
 };

bin/dependency-cruise.mjs

@@ -56,7 +56,11 @@ try {
  )
  .option(
  "-R, --reaches <regex>",
- "only include modules matching the regex + all modules that can reach it",
+ "only include modules matching the regex + all modules that can reach them",
+ )
+ .option(
+ "-A, --affected [revision]",
+ "only include modules changed since the revision + all modules that can reach them (when not specified revision defaults to 'main')",
  )
  .option(
  "-H, --highlight <regex>",

doc/cli.md

@@ -34,6 +34,7 @@ available in dependency-cruiser configurations.
 1. [`--focus`: show modules and their neighbours](#--focus-show-modules-and-their-neighbours)
 1. [`--focus-depth`: influence how many layers of neighbors --focus shows](#--focus-depth-influence-how-many-layers-of-neighbors---focus-shows)
 1. [`--reaches`: show modules and their transitive dependents](#--reaches-show-modules-and-their-transitive-dependents)
+1. [`--affected`: show modules and their transitive dependents since a git `revision`](#--affected-show-modules-and-their-transitive-dependents-since-a-git-revision)
 1. [`--highlight`: highlight modules](#--highlight-highlight-modules)
 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)
@@ -942,6 +943,10 @@ for more details
 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.
 
+> [!NOTE]
+> If you're using `git` for revision control the `--affected` option might be
+> a better fit for you.
+
 Just like the filter options above, takes a regular expression:
 
 ```sh
@@ -951,6 +956,45 @@ dependency-cruise src --include-only "^src/report" --reaches "^src/report/utl/in
 See [reaches](./options-reference.md#reaches-show-modules-matching-a-pattern---with-everything-that-can-reach-them)
 in the options reference for more details.
 
+### `--affected`: show modules and their transitive dependents since a git `revision`
+
+Only include modules changed since the revision + all modules that can reach them.
+For 'revision' you can use everything git understands as a revision (e.g. a commit
+hash, a branch name, a tag, HEAD~1, etc.).
+
+When not specified, _revision_ defaults to `main`.
+
+This can be useful when you want to see the modules that are impacted by a change
+you made.
+
+```sh
+dependency-cruise src --affected main -T dot | dot -T svg > affected-example.svg
+```
+
+In combination with the `mermaid` reporter you can use it in your github action
+workflow to generate a graph of the affected modules and put it in a PR comment
+or in the workflow summary:
+
+````yaml
+- name: on pull requests emit the affected graph to the step summary with changed modules highlighted
+ if: always() && github.event_name == 'pull_request' && github.ref_name != github.event.repository.default_branch
+ run: |
+ echo '## Modules changed and affected by this PR' >> $GITHUB_STEP_SUMMARY
+ echo Modules changed in this PR have a fluorescent green color. All other modules in the graph are those directly or indirectly affected by changes in the green modules. >> $GITHUB_STEP_SUMMARY
+ echo '```mermaid' >> $GITHUB_STEP_SUMMARY
+ npx dependency-cruiser src test --output-type mermaid --affected ${{github.event.pull_request.base.sha}} >> $GITHUB_STEP_SUMMARY
+ echo '' >> $GITHUB_STEP_SUMMARY
+ echo '```' >> $GITHUB_STEP_SUMMARY
+````
+
+> This option is 'syntactic sugar' around the `--reaches` option. These invocations
+> are equivalent:
+>
+> ```sh
+> dependency-cruise src --affected -T dot | dot -T svg > affected-with-affectd.svg
+> dependency-cruise src --reaches "$(watskeburt main)" -T dot | dot -T svg > affected-with-reaches.svg
+> ```
+
 ### `--highlight`: highlight modules
 
 This option takes a regular expression and reporters that recognize the

package.json

@@ -156,9 +156,9 @@
  "depcruise:graph:doc:fmt-types": "cd types && node ../bin/dependency-cruise.mjs . --output-type dot | dot -T svg | tee overview.svg | ../bin/wrap-stream-in-html.mjs > overview.html && cd -",
  "depcruise:graph:doc:samples": "sh tools/generate-samples.sh",
  "depcruise:graph:mermaid": "node ./bin/dependency-cruise.mjs bin src --include-only ^src/ --collapse 2 --output-type mermaid",
- "depcruise:graph:mermaid:diff": "node ./bin/dependency-cruise.mjs bin src test types tools --config configs/.dependency-cruiser-unlimited.mjs --output-type mermaid --reaches \"$(watskeburt $SHA)\"",
+ "depcruise:graph:mermaid:diff": "node ./bin/dependency-cruise.mjs bin src test types tools --config configs/.dependency-cruiser-unlimited.mjs --output-type mermaid --affected $SHA",
  "depcruise:graph:view": "node ./bin/dependency-cruise.mjs bin src --prefix vscode://file/$(pwd)/ --config configs/.dependency-cruiser-show-metrics-config.mjs --output-type x-dot-webpage --progress cli-feedback --highlight \"$(watskeburt main)\" | browser",
- "depcruise:graph:view:diff": "node ./bin/dependency-cruise.mjs bin src test --prefix vscode://file/$(pwd)/ --config configs/.dependency-cruiser-unlimited.mjs --output-type x-dot-webpage --progress cli-feedback --reaches \"$(watskeburt main)\" | browser",
+ "depcruise:graph:view:diff": "node ./bin/dependency-cruise.mjs bin src test --prefix vscode://file/$(pwd)/ --config configs/.dependency-cruiser-unlimited.mjs --output-type x-dot-webpage --progress cli-feedback --affected | browser",
  "depcruise:report": "node ./bin/dependency-cruise.mjs src bin test configs types --output-type err-html --config configs/.dependency-cruiser-show-metrics-config.mjs --output-to dependency-violations.html",
  "depcruise:report:view": "node ./bin/dependency-cruise.mjs src bin test configs types --output-type err-html --config configs/.dependency-cruiser-show-metrics-config.mjs --output-to - | browser",
  "depcruise:focus": "node ./bin/dependency-cruise.mjs src bin test configs types tools --progress --no-cache --output-type text --focus",
@@ -311,4 +311,4 @@
  "vue-template-compiler": ">=2.0.0 <3.0.0",
  "@vue/compiler-sfc": ">=3.0.0 <4.0.0"
  }
-}
+}

src/cli/normalize-cli-options.mjs

@@ -222,6 +222,15 @@ export default async function normalizeOptions(pOptionsAsPassedFromCommander) {
  lOptions = normalizeConfigFileName(lOptions, "webpackConfig", WEBPACK_CONFIG);
  lOptions = normalizeConfigFileName(lOptions, "tsConfig", TYPESCRIPT_CONFIG);
  lOptions = normalizeConfigFileName(lOptions, "babelConfig", BABEL_CONFIG);
+ if (Object.hasOwn(lOptions, "affected") && lOptions.affected !== false) {
+ const { list } = await import("watskeburt");
+ lOptions.reaches = await list({
+ oldRevision: lOptions.affected === true ? "main" : lOptions.affected,
+ outputType: "regex",
+ extensions:
+ "cjs,cjsx,coffee,csx,cts,js,json,jsx,litcoffee,ls,mjs,mts,svelte,ts,tsx,vue,vuex",
+ });
+ }
 
  return lOptions;
 }