feature(*): add focus option

[sverweij]

Description

• Adds an option to 'focus' on a bunch of modules, so the output contains:

1. the modules matching the regular expression in the focus option
2. the modules that are direct dependencies of 1.
3. the modules that directly depend on 1.

When you use this option, in the internal data structure each module grows a matchesFocus attribute that has the value true for modules in 1. , false for all modules. This can be helpful for e.g. use in graphical output (see the screenshots below for an example).

• This PR also makes the processing of filter options more uniform:
  • all filter options can be specified either as a string (focus: "^src/main") or as an object (focus: {path: "^src/main"})
  • internally filter options are represented as the object variant.

This makes sure processing for all filters is uniform, and can be extended easily (while remaining backwards compatible).

Motivation and Context

• fixes Feature request: Is it possible to show up- and downstream nodes of a file or directory? #290

How Has This Been Tested?

• Additional automated tests
• Green CI

Sample and screenshots

Example usage:

depcruise src --focus "^src/main" -v .depcruise-options.js -T dot | dot -T svg > focused-graph.svg

with this `.depcruise-options.js`

This demonstrates the use of the matchesFocus attribute to tweak the dot report. This colors the modules that directly match the 'focus' pattern green, and the rest lighgray:

module.exports = {
  options: {
    includeOnly: "^src",
    reporterOptions: {
      dot: {
        collapsePattern: "node_modules/[^/]+",
        theme: {
          graph: {
            // "ortho" makes graphviz use orthogonal routing. When slow use "true" in stead.
            splines: "ortho",
          },
          modules: [
            {
              criteria: { matchesFocus: true },
              attributes: { fillcolor: "#ccffcc" },
            },
            {
              criteria: { matchesFocus: false },
              attributes: { fillcolor: "#dddddd" },
            },
          ],
        },
      },
    },
  },
};

Which will yield:

For reference you can compare this with the complete internal dependency-graph, which you can find here

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)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• 📖

  • My change doesn't require a documentation update, or ...
  • it does and I have updated it

• ⚖️

  • The contribution will be subject to The MIT license, and I'm OK with that.
  • The contribution is my own original work.
  • I am ok with the stuff in CONTRIBUTING.md.

[codeclimate]

The PR diff size of 7574 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8429 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8432 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8430 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8446 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8634 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8634 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8811 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 8820 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 11169 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 9463 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

The PR diff size of 10002 lines exceeds the maximum allowed for the inline comments feature.

[codeclimate]

Code Climate has analyzed commit 7af2aa1 and detected 0 issues on this pull request.

The test coverage on the diff in this pull request is 100.0% (99% is the threshold).

This pull request will bring the total coverage in the repository to 99.9% (0.0% change).

View more on Code Climate.