Throw an error when there are more ToC roots than expected

As an unexpected extra ToC root likely indicates a mistake.

Should make it easier to find inconsistencies like those
that triggered #316

core/src/main/scala/com/lightbend/paradox/ParadoxProcessor.scala

@@ -28,6 +28,8 @@ import org.stringtemplate.v4.STErrorListener
 
 import scala.annotation.tailrec
 import scala.collection.JavaConverters._
+import org.stringtemplate.v4.misc.STMessage
+import org.stringtemplate.v4.misc.ErrorType
 
 /**
  * Markdown site processor.
@@ -48,13 +50,14 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
     navDepth:           Int,
     navExpandDepth:     Option[Int],
     navIncludeHeaders:  Boolean,
+    expectedRoots:      Int,
     pageTemplate:       PageTemplate,
     errorListener:      STErrorListener): Seq[(File, String)] = {
     require(!groups.values.flatten.map(_.toLowerCase).groupBy(identity).values.exists(_.size > 1), "Group names may not overlap")
 
-    val pages = parsePages(mappings, Path.replaceSuffix(sourceSuffix, targetSuffix), properties)
-    val paths = Page.allPaths(pages).toSet
-    val globalPageMappings = rootPageMappings(pages)
+    val roots = parsePages(mappings, Path.replaceSuffix(sourceSuffix, targetSuffix), properties)
+    val paths = Page.allPaths(roots).toSet
+    val globalPageMappings = rootPageMappings(roots)
 
     val navToc = new TableOfContents(pages = true, headers = navIncludeHeaders, ordered = false, maxDepth = navDepth, maxExpandDepth = navExpandDepth)
     val pageToc = new TableOfContents(pages = false, headers = true, ordered = false, maxDepth = navDepth)
@@ -73,8 +76,13 @@ class ParadoxProcessor(reader: Reader = new Reader, writer: Writer = new Writer)
         render(loc.next, rendered :+ (outputFile, page.path))
       case None => rendered
     }
+
+    if (expectedRoots != roots.size)
+      throw new IllegalStateException(s"Expected $expectedRoots ToC roots (based on paradoxExpectedNumberOfRoots) but found ${roots.size}: " +
+        roots.map(_.label.path).mkString("[", ", ", "]"))
+
     outputDirectory.mkdirs()
-    createMetadata(outputDirectory, properties) :: (pages flatMap { root => render(Some(root.location)) })
+    createMetadata(outputDirectory, properties) :: (roots flatMap { root => render(Some(root.location)) })
   }
 
   private def createMetadata(outputDirectory: File, properties: Map[String, String]): (File, String) = {

plugin/src/main/scala/com/lightbend/paradox/sbt/ParadoxKeys.scala

@@ -27,6 +27,7 @@ trait ParadoxKeys {
   val paradoxNavigationDepth = settingKey[Int]("Determines depth of TOC for page navigation.")
   val paradoxNavigationExpandDepth = settingKey[Option[Int]]("Depth of auto-expanding navigation below the active page.")
   val paradoxNavigationIncludeHeaders = settingKey[Boolean]("Whether to include headers in the navigation.")
+  val paradoxExpectedNumberOfRoots = settingKey[Int]("How many ToC roots to expect.")
   val paradoxLeadingBreadcrumbs = settingKey[List[(String, String)]]("Any leading breadcrumbs (label -> url)")
   val paradoxOrganization = settingKey[String]("Paradox dependency organization (for theme dependencies).")
   val paradoxDirectives = taskKey[Seq[Writer.Context => Directive]]("Enabled paradox directives.")

plugin/src/main/scala/com/lightbend/paradox/sbt/ParadoxPlugin.scala

@@ -49,6 +49,7 @@ object ParadoxPlugin extends AutoPlugin {
     paradoxNavigationDepth := 2,
     paradoxNavigationExpandDepth := None,
     paradoxNavigationIncludeHeaders := false,
+    paradoxExpectedNumberOfRoots := 1,
     paradoxDirectives := Writer.defaultDirectives,
     paradoxProperties := Map.empty,
     paradoxTheme := Some(builtinParadoxTheme("generic")),
@@ -165,6 +166,7 @@ object ParadoxPlugin extends AutoPlugin {
           paradoxNavigationDepth.value,
           paradoxNavigationExpandDepth.value,
           paradoxNavigationIncludeHeaders.value,
+          paradoxExpectedNumberOfRoots.value,
           paradoxTemplate.value,
           new PageTemplate.ErrorLogger(s => strms.log.error(s))
         )

plugin/src/sbt-test/paradox/default-theme/build.sbt

@@ -4,4 +4,5 @@ lazy val docs = project
   .settings(
     name := "Paradox Default Theme Test",
     paradoxProperties += ("canonical.base_url" -> "https://example.com/doc/"),
+    paradoxExpectedNumberOfRoots := 2,
   )

plugin/src/sbt-test/paradox/docs-overlay/build.sbt

@@ -9,5 +9,7 @@ lazy val docs = (project in file(".")).
     ParadoxPlugin.paradoxSettings(DocsSecond),
     // paradoxOverlayDirectories := Seq(baseDirectory.value / "src" / "commonFirst"),
     paradoxOverlayDirectories in DocsFirst := Seq(baseDirectory.value / "src" / "commonFirst"),
-    paradoxOverlayDirectories in DocsSecond := Seq(baseDirectory.value / "src" / "commonFirst", baseDirectory.value / "src" / "commonSecond")
-  )
+    paradoxOverlayDirectories in DocsSecond := Seq(baseDirectory.value / "src" / "commonFirst", baseDirectory.value / "src" / "commonSecond"),
+    paradoxExpectedNumberOfRoots in DocsFirst := 4,
+    paradoxExpectedNumberOfRoots in DocsSecond := 6,
+  )

plugin/src/sbt-test/paradox/parameterized-links/build.sbt

@@ -15,6 +15,7 @@ paradoxProperties in Compile ++= Map(
   "javadoc.akka.base_url" -> s"http://doc.akka.io/japi/akka/$akkaVersion",
   "javadoc.akka.http.base_url" -> s"http://doc.akka.io/japi/akka-http/$akkaHttpVersion"
 )
+paradoxExpectedNumberOfRoots := 5
 
 apiURL := Some(url(s"https://example.org/api/${version.value}"))
 scmInfo := Some(ScmInfo(url("https://github.com/lightbend/paradox"), "git@github.com:lightbend/paradox.git"))

plugin/src/sbt-test/paradox/snippets/build.sbt

@@ -4,5 +4,6 @@ lazy val docs = (project in file(".")).
     paradoxTheme := None,
     paradoxProperties in Compile ++= Map(
       "snip.test.base_dir" -> (sourceDirectory in Test).value.toString,
-      "snip.test-scala.base_dir" -> "../../test/scala")
-  )
+      "snip.test-scala.base_dir" -> "../../test/scala"),
+    paradoxExpectedNumberOfRoots := 7,
+  )