Add max level option

Author: steinybot

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
         run: sbt ++${{ matrix.scala }} scripted
 
       - name: Compress target directories
-        run: tar cf targets.tar sbt/target target doc-templates/target cli/target core/target example/target project/target
+        run: tar cf targets.tar sbt/target target meta/docs/target cli/target core/target example/target project/target
 
       - name: Upload target directories
         uses: actions/upload-artifact@v2

README.md

@@ -37,7 +37,7 @@ For most use cases you should add Scala2PlantUML as a global plugin since your b
 Create `~/.sbt/1.0/plugins/scala2PlantUML.sbt` containing:
 
 ```text
-addSbtPlugin("nz.co.bottech" % "sbt-scala2plantuml" % "0.1.12")
+addSbtPlugin("nz.co.bottech" % "sbt-scala2plantuml" % "0.2.0")
 ```
 
 ## CLI
@@ -52,20 +52,23 @@ cs install --channel https://git.io/Jqv1i scala2plantuml
 
 ### Usage
 
+```shell
+scala2plantuml --help
+```
+
 ```text
-> scala2plantuml --help
-Scala2PlantUML version 0.1.12
+Scala2PlantUML version 0.2.0
 Usage: scala2plantuml [options] symbol
 
 Scala2PlantUML generates PlantUML Class Diagrams from Scala SemanticDB files.
 
   symbol                   The symbol to use as the starting point for generating the diagram.
-
+                           
                            To get a symbol from a class name, convert the package name separate '.' to '/' and add a '#'
                            suffix. For an object use a suffix of '.'.
-
+                           
                            See https://scalameta.org/docs/semanticdb/specification.html#symbol-1 for the full syntax.
-
+                           
                            Examples:
                              'com/example/Foo#' (class com.example.Foo)
                              'com/example/Foo.' (object com.example.Foo)
@@ -79,16 +82,16 @@ The pattern supports two wildcards:
 2) *  (matches all characters except for '/')
 
   -i, --include <pattern>  Only include symbols that match the pattern.
-
+                           
                            Default: '**'
-
+                           
                            Example:
                              --include 'com/example/**/model/*'
 
   -e, --exclude <pattern>  Excludes all symbols that match the pattern.
-
+                           
                            Default: 'scala/**', 'java/**'
-
+                           
                            Example:
                              --exclude 'com/example/**/data/*'
 
@@ -98,62 +101,190 @@ Each of these can be provided multiple times.
 By default, the classpath that was used when executing Scala2PlantUML is also used.
 
   -d, --dir <dir>          Directories of the SemanticDB target roots containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --dir 'my-project/target/scala-2.13/meta'
 
   -j, --jar <jar>          JAR containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --jar 'foo.jar'
 
   -u, --url <url>          A URL to a JAR containing META-INF/semanticdb/**/*.semanticdb files.
-
+                           
                            Example:
                              --url 'https://repo1.maven.org/maven2/com/example/foo/foo_2.13/1.0.0/foo_2.13-1.0.0-semanticdb.jar'
 
 The --project and --source options specify where within the search locations the SemanticDB files can be found.
 Each of these can be provided multiple times. The result will be all combinations of projects and source roots.
 
   -p, --project <project>  The name of the projects that have SemanticDB files.
-
+                           
                            The project name will be used when looking for SemanticDB files such as:
                            META-INF/semanticdb/<project>/<source>/*.semanticdb
-
+                           
                            An empty project name will search in:
                            META-INF/semanticdb/<source>/*.semanticdb
-
+                           
                            Default: ''
-
+                           
                            Example:
                              --project my-project
 
   -s, --source <source>    The directory relative to the project where the source files were located.
-
+                           
                            The source will be used when looking for SemanticDB files such as
                            META-INF/semanticdb/<project>/<source>/*.semanticdb.
-
+                           
                            Default: src/main/scala
-
+                           
                            Example:
                              --source 'source/scala'
 
-  -o, --output <file>      Write the output to the given file.
+  -l, --max-level <level>  The maximum number of levels that will be traversed when following symbol references.
+                           
+                           This means that parent symbols that would be beyond the max level will not be shown.
+                           
+                           A diagram with a max-level of 1 will only contain the initial symbol.
+                           
+                           Default: Unlimited
+                           
+                           Example:
+                             --max-level 3
 
+  -o, --output <file>      Write the output to the given file.
+                           
                            Example:
                              --output docs/diagrams/my-project.puml
 
   -c, --colour <value>     Enables coloured output.
-
+                           
                            Default: true
-
+                           
                            Example:
                              --colour false
 
   -v, --verbose            Increases the log level.
-
+                           
                            This can be provided twice for the most verbose logging.
+                           
+                           Example:
+                             -vv
+
+  -h, --help
+  --version
+Error: Missing argument symbol
+Scala2PlantUML version 0.2.0
+Usage: scala2plantuml [options] symbol
+
+Scala2PlantUML generates PlantUML Class Diagrams from Scala SemanticDB files.
+
+  symbol                   The symbol to use as the starting point for generating the diagram.
+                           
+                           To get a symbol from a class name, convert the package name separate '.' to '/' and add a '#'
+                           suffix. For an object use a suffix of '.'.
+                           
+                           See https://scalameta.org/docs/semanticdb/specification.html#symbol-1 for the full syntax.
+                           
+                           Examples:
+                             'com/example/Foo#' (class com.example.Foo)
+                             'com/example/Foo.' (object com.example.Foo)
+                             'com/example/Foo.bar.' (value/variable bar on object com.example.Foo)
+                             'com/example/Foo#baz().' (function baz on class com.example.Foo)
+
+The --include and --exclude options control which symbols will be processed. Each of these can be provided multiple times.
+
+The pattern supports two wildcards:
+1) ** (matches any character)
+2) *  (matches all characters except for '/')
+
+  -i, --include <pattern>  Only include symbols that match the pattern.
+                           
+                           Default: '**'
+                           
+                           Example:
+                             --include 'com/example/**/model/*'
 
+  -e, --exclude <pattern>  Excludes all symbols that match the pattern.
+                           
+                           Default: 'scala/**', 'java/**'
+                           
+                           Example:
+                             --exclude 'com/example/**/data/*'
+
+The --dir, --jar, and --url options specify the directories and JAR files that are used when locating SemanticDB files.
+Each of these can be provided multiple times.
+
+By default, the classpath that was used when executing Scala2PlantUML is also used.
+
+  -d, --dir <dir>          Directories of the SemanticDB target roots containing META-INF/semanticdb/**/*.semanticdb files.
+                           
+                           Example:
+                             --dir 'my-project/target/scala-2.13/meta'
+
+  -j, --jar <jar>          JAR containing META-INF/semanticdb/**/*.semanticdb files.
+                           
+                           Example:
+                             --jar 'foo.jar'
+
+  -u, --url <url>          A URL to a JAR containing META-INF/semanticdb/**/*.semanticdb files.
+                           
+                           Example:
+                             --url 'https://repo1.maven.org/maven2/com/example/foo/foo_2.13/1.0.0/foo_2.13-1.0.0-semanticdb.jar'
+
+The --project and --source options specify where within the search locations the SemanticDB files can be found.
+Each of these can be provided multiple times. The result will be all combinations of projects and source roots.
+
+  -p, --project <project>  The name of the projects that have SemanticDB files.
+                           
+                           The project name will be used when looking for SemanticDB files such as:
+                           META-INF/semanticdb/<project>/<source>/*.semanticdb
+                           
+                           An empty project name will search in:
+                           META-INF/semanticdb/<source>/*.semanticdb
+                           
+                           Default: ''
+                           
+                           Example:
+                             --project my-project
+
+  -s, --source <source>    The directory relative to the project where the source files were located.
+                           
+                           The source will be used when looking for SemanticDB files such as
+                           META-INF/semanticdb/<project>/<source>/*.semanticdb.
+                           
+                           Default: src/main/scala
+                           
+                           Example:
+                             --source 'source/scala'
+
+  -l, --max-level <level>  The maximum number of levels that will be traversed when following symbol references.
+                           
+                           This means that parent symbols that would be beyond the max level will not be shown.
+                           
+                           A diagram with a max-level of 1 will only contain the initial symbol.
+                           
+                           Default: Unlimited
+                           
+                           Example:
+                             --max-level 3
+
+  -o, --output <file>      Write the output to the given file.
+                           
+                           Example:
+                             --output docs/diagrams/my-project.puml
+
+  -c, --colour <value>     Enables coloured output.
+                           
+                           Default: true
+                           
+                           Example:
+                             --colour false
+
+  -v, --verbose            Increases the log level.
+                           
+                           This can be provided twice for the most verbose logging.
+                           
                            Example:
                              -vv
 

build.sbt

@@ -21,6 +21,7 @@ addCommandAlias(
   List(
     "scalafmtCheckAll",
     "scalastyle",
+    "versionCheck",
     "versionPolicyCheck",
     "docs/mdoc --check",
     "evicted",
@@ -79,14 +80,14 @@ inThisBuild(
     // This needs to be set otherwise the GitHub workflow plugin gets confused about which
     // version to use for the publish job.
     scalaVersion := scala212,
-    versionPolicyFirstVersion := Some("0.1.12"),
     versionPolicyIntention := Compatibility.BinaryAndSourceCompatible,
     versionScheme := Some("early-semver")
   )
 )
 
 val commonProjectSettings = List(
   isScala213 := isScala213Setting.value,
+  name := s"${(LocalRootProject / name).value}-${name.value}",
   scalastyleFailOnError := true,
   scalastyleFailOnWarning := true,
   // Workaround for https://github.com/cb372/sbt-explicit-dependencies/issues/97
@@ -102,7 +103,6 @@ val commonProjectSettings = List(
 )
 
 val metaProjectSettings = List(
-  crossScalaVersions := Nil,
   mimaFailOnNoPrevious := false,
   mimaPreviousArtifacts := Set.empty,
   publish / skip := true
@@ -153,8 +153,7 @@ lazy val cli = project
       "ch.qos.logback"    % "logback-core"    % logbackVersion,
       "com.github.scopt" %% "scopt"           % scoptVersion,
       "org.slf4j"         % "slf4j-api"       % slf4jVersion
-    ),
-    name := s"${(LocalRootProject / name).value}-cli"
+    )
   )
 
 lazy val sbtProject = (project in file("sbt"))
@@ -192,31 +191,36 @@ lazy val sbtProject = (project in file("sbt"))
     scriptedLaunchOpts += s"-Dplugin.version=${version.value}"
   )
 
-lazy val docs = (project in file("doc-templates"))
-  .enablePlugins(MdocPlugin)
+lazy val docs = (project in file("meta/docs"))
+  // Include build info here so that we can override the version.
+  .enablePlugins(BuildInfoPlugin, MdocPlugin)
+  .dependsOn(cli)
   .settings(metaProjectSettings)
   .settings(
+    // We use a different version setting so that it may depend on versionPolicyPreviousVersions
+    // without creating a cycle. This means that we need to map the identifier back so that it
+    // matches the same key used when compiling the build info for the CLI.
+    buildInfoKeys := Seq[BuildInfoKey](BuildInfoKey.map(mdoc / version)({ case (_, value) => "version" -> value })),
+    buildInfoPackage := s"${organization.value}.${(LocalRootProject / name).value}",
     libraryDependencies := libraryDependencies.value.map { module =>
       if (module.name.startsWith("mdoc"))
         module.exclude("io.undertow", "undertow-core").exclude("org.jboss.xnio", "xnio-nio")
       else module
     },
     mdocOut := (ThisBuild / baseDirectory).value,
     mdocVariables := Map(
-      // This is configured for GitHub where we want to show the previous version.
-      // After a release we need to update the docs and do a git push.
-      "VERSION" -> versionPolicyPreviousVersions.value.lastOption.getOrElse(versionPolicyFirstVersion.value.get)
+      "VERSION" -> (mdoc / version).value
     ),
-    unusedCompileDependenciesFilter -= moduleFilter("org.scalameta", "mdoc*")
+    unusedCompileDependenciesFilter -= moduleFilter("org.scalameta", "mdoc*"),
+    mdoc / version := versionPolicyPreviousVersions.value.lastOption.getOrElse(version.value)
   )
 
 lazy val example = project
   .settings(commonProjectSettings)
   .settings(
     semanticdbEnabled := true,
     semanticdbIncludeInJar := true,
-    semanticdbVersion := sdbVersion,
-    versionPolicyFirstVersion := Some("0.1.13"),
+    semanticdbVersion := sdbVersion
   )
 
 def isScala213Setting: Def.Initialize[Boolean] = Def.setting {

cli/src/main/scala/nz/co/bottech/scala2plantuml/Config.scala

@@ -14,7 +14,8 @@ final case class Config(
     sourceRoots: Vector[String] = Vector("src/main/scala"),
     outputFile: Option[File] = None,
     logInColour: Boolean = true,
-    logLevel: Int = 0) {
+    logLevel: Int = 0,
+    maxLevel: Option[Int] = None) {
 
   def addInclude(pattern: String): Config =
     copy(includes = includes + pattern)