Skip to content

Latest commit

 

History

History
180 lines (150 loc) · 9.59 KB

README.md

File metadata and controls

180 lines (150 loc) · 9.59 KB
Raw

Module Graph Assert

A Gradle plugin that helps keep your module graph healthy and lean.

Build Gradle Plugin

What is changed in this fork

Important

Added support for Mermaid output format supported by GitHub / GitLab markdown. So we can draw dependency chart into markdown file.

Usage for GitHub / GitLab markdown

// app/build.gradle.kts
plugins { 
  id("cz.mtrakal.module.graph.assertion") version "2.5.0"
}


moduleGraphAssert {
    configurations = setOf("api", "implementation")
    assertOnAnyBuild = true
    outputFormat = OutputFormat.MERMAID
    outputFilePath = "$rootDir/dependency-graph.md"
}

Original info from forked repository by JRaska

example_graph

Why the module dependency structure matters

  • Build speeds can be very dependent on the structure of your module graph.
  • Modules separate logical units and enforce proper dependencies.
  • The module graph can silently degenerate into a list-like structure.
  • Breaking problematic module dependencies can be very difficult, it is cheaper to prevent them.
  • If not enforced, undesirable module dependencies will appear. Murphy's law of dependencies: "Whatever they can access, they will access."

What we can enforce

  • The plugin provides a simple way for defining rules, which will be verified with the task assertModuleGraph as part of the check task.
  • Match module names using regular expressions.
  • Define the only allowed dependencies between modules
    • allowed = [':feature-one -> :feature-[a-z-:]*', ':.* -> :core', ':feature.* -> :lib.*'] define rules by using regex -> regex signature.
    • Dependency, which will not match any of those rules will fail the assertion.
  • restricted [':feature-[a-z]* -X> :forbidden-to-depend-on'] helps us to define custom rules by using regex -X> regex signature.
  • maxHeight = 4 can verify that the height of the modules tree with a root in the module will not exceed 4. Tree height is a good metric to prevent module tree degeneration into a list.

Usage

Apply the plugin to a module, which dependencies graph you want to assert.

plugins {
  id "cz.mtrakal.module.graph.assertion" version "3.0.0"
}
  • You can run ./gradlew assertModuleGraph to execute configured checks or ./gradlew check where assertModuleGraph will be included.
  • Alternative option is using assertOnAnyBuild = true configuration to run the checks on every single Gradle build without need for running explicit tasks - see jraska#184 for more details.
  • Hint: Gradle Configuration On Demand may hide some modules from the plugin visibility. If you notice some modules are missing, try the --no-configure-on-demand flag.

Configuration

Rules are applied on the Gradle module and its api and implementation dependencies by default. Typically you would want to apply this in your final app module, however configuration for any module is possible. Example

moduleGraphAssert {
//    maxHeight = 4
  // regex to match module names
  allowed = setOf(".* -> :core", ":feature.* -> :lib.*")
  // regex to match module names
  restricted = setOf(":feature-[a-z]* -X> :forbidden-to-depend-on")
  // Dependency configurations to look. ['api', 'implementation'] is the default
  configurations = setOf("api", "implementation")
  // true value will run the assertions as part of any build without need to run the assert* tasks, false is default
  assertOnAnyBuild = true

  // Output format for generated file (default is OutputFormat.GRAPHWIZ)
  outputFormat = OutputFormat.MERMAID
  // Output file path for generated graph file
  outputFilePath = "$rootDir/dependency-graph.md"
}
Deprecated Groovy format 
moduleGraphAssert {
  maxHeight = 4
  allowed = [':.* -> :core', ':feature.* -> :lib.*'] // regex to match module names
  restricted = [':feature-[a-z]* -X> :forbidden-to-depend-on'] // regex to match module names
  configurations = ['api', 'implementation'] // Dependency configurations to look. ['api', 'implementation'] is the default
  assertOnAnyBuild = false // true value will run the assertions as part of any build without need to run the assert* tasks, false is default
}

Module name alias

  • You don't have to rely on module names and set a property ext.moduleNameAssertAlias = "ThisWillBeAssertedOn"
  • This can be set on any module and the allowed/restricted rules would use the alias instead of module name for asserting.
  • This is useful for example if you want to use "module types" where each module has a type regardless the name and you want to manage only dependnecies of different types.
  • It is recommended to use either module names or moduleNameAssertAlias everywhere. Mixing both is not recommended.
  • Example of module rules you could implement for a flat module graph:

`

  • Each module would have set ext.moduleNameAssertAlias = "Api|Implementation|App"
  • Module rules example for such case: allowed = ['Implementation -> Api', 'App -> Implementation', 'App -> Api']
  • In case you want to migrate to this structure incrementally, you can set a separate module type like ext.moduleNameAssertAlias = "NeedsMigration" and setting
allowed = [
  'Implementation -> Api', 
  'App -> Implementation', 
  'App -> Api', 
  'NeedsMigration -> .*', 
  '.* -> NeedsMigration'
]
  • "NeedsMigration" modules can be then tackled one by one to move them into Implementation or Api type. Example of app with this structure can be seen here.

Graphviz Graph Export

  • Visualising the graph could be useful to help find your dependency issues, therefore a helper generateModulesGraphvizText task is included.
  • This generates a graph of dependent modules when the plugin is applied.
  • The longest path of the project is in red.
  • If you utilise Configuration on demand Gradle feature, please use --no-configure-on-demand flag along the generateModulesGraphvizText task.
  • You can set the modules.graph.of.module parameter if you are only interested in a sub-graph of the module graph.
./gradlew generateModulesGraphvizText -Pmodules.graph.of.module=:feature-one
  • Adding the parameter modules.graph.output.gv saves the graphViz file to the specified path
./gradlew generateModulesGraphvizText -Pmodules.graph.output.gv=all_modules

Mermaid Graph Export

  • Visualising the graph could be useful to help find your dependency issues, therefore a helper generateModulesMermaidText task is included.
  • This generates a graph of dependent modules when the plugin is applied.
  • The longest path of the project is in red.
  • If you utilise Configuration on demand Gradle feature, please use --no-configure-on-demand flag along the generateModulesMermaidText task.
  • You can set the modules.graph.of.module parameter if you are only interested in a sub-graph of the module graph.
./gradlew --no-configure-on-demand generateModulesMermaidText -P "modules.graph.of.module=:feature-one"
  • Adding the parameter modules.graph.output.mermaid saves the mermaid file to the specified path
./gradlew --no-configure-on-demand generateModulesMermaidText -P "modules.graph.output.mermaid=all_modules"

Graph statistics

  • Executing the task generateModulesGraphStatistics prints the information about the graph.
  • Statistics printed: Modules Count, Edges Count, Height and Longest Path
  • Parameter -Pmodules.graph.of.module is supported as well.
./gradlew generateModulesGraphStatistics -Pmodules.graph.of.module=:feature-one

Contributing

Please feel free to create PR or issue with any suggestions or ideas. No special format required, just common sense.

Debugging

Setting up a composite build

Composite builds are consumed directly without publishing a version.

settings.gradle:

includeBuild("path/to/modules-graph-assert")

Root build.gradle:

plugins {
  id('cz.mtrakal.module.graph.assertion')
}