Add --verbose flag

It's difficult to debug link hygiene bugs since we don't know what links
are valid. Eventually, we might implement some levenstein distance.

mdoc-docs/src/main/scala/mdoc/docs/MdocModifier.scala

@@ -25,7 +25,7 @@ class MdocModifier(context: Context) extends StringModifier {
     val cleanInput = Input.VirtualFile(code.filename, code.text)
     val markdown = Markdown.toMarkdown(cleanInput, markdownSettings, myReporter, context.settings)
     val links = DocumentLinks.fromMarkdown(GitHubIdGenerator, RelativePath("readme.md"), cleanInput)
-    LinkHygiene.lint(List(links), myReporter)
+    LinkHygiene.lint(List(links), myReporter, verbose = false)
     val stdout = fansi.Str(myStdout.toString()).plainText
     if (myReporter.hasErrors || myReporter.hasWarnings) {
       if (info != "crash") {

mdoc/src/main/scala/mdoc/internal/cli/MainOps.scala

@@ -29,7 +29,7 @@ final class MainOps(
 
   def lint(): Unit = {
     val docs = DocumentLinks.fromGeneratedSite(settings, reporter)
-    LinkHygiene.lint(docs, reporter)
+    LinkHygiene.lint(docs, reporter, settings.verbose)
   }
 
   def handleMarkdown(file: InputFile): Exit = synchronized {

mdoc/src/main/scala/mdoc/internal/cli/Settings.scala

@@ -51,6 +51,8 @@ case class Settings(
     )
     @ExtraName("test")
     check: Boolean = false,
+    @Description("Include additional diagnostics for debuggin potential problems.")
+    verbose: Boolean = false,
     @Description(
       "Classpath to use when compiling Scala code examples. " +
         "Defaults to the current thread's classpath."

mdoc/src/main/scala/mdoc/internal/markdown/LinkHygiene.scala

@@ -4,7 +4,7 @@ import java.net.URI
 import mdoc.Reporter
 
 object LinkHygiene {
-  def lint(docs: List[DocumentLinks], reporter: Reporter): Unit = {
+  def lint(docs: List[DocumentLinks], reporter: Reporter, verbose: Boolean): Unit = {
     val isValidHeading = docs.iterator.flatMap(_.absoluteDefinitions).toSet
     for {
       doc <- docs
@@ -15,11 +15,14 @@ object LinkHygiene {
       if !isValidHeading(uri)
     } {
       val isAbsolutePath = uri.getPath.startsWith("/")
+      val debug =
+        if (verbose) s". isValidHeading=$isValidHeading"
+        else ""
       val hint =
         if (isAbsolutePath)
           s". To fix this problem, either make the link relative or turn it into complete URL such as http://example.com$uri."
         else ""
-      reporter.warning(reference.pos, s"Unknown link '$uri'$hint")
+      reporter.warning(reference.pos, s"Unknown link '$uri'$hint$debug")
     }
   }
 

readme.md

@@ -727,6 +727,9 @@ Common options:
     produce a diff against an existing site. Useful for asserting in CI that a
     site is up-to-date.
 
+  --verbose
+    Include additional diagnostics for debuggin potential problems.
+
   --classpath String (default: "")
     Classpath to use when compiling Scala code examples. Defaults to the current
     thread's classpath.

tests/unit/src/test/scala/tests/markdown/LinkHygieneSuite.scala

@@ -13,7 +13,7 @@ import mdoc.internal.markdown.LinkHygiene
 class LinkHygieneSuite extends FunSuite with DiffAssertions {
   private val myOut = new ByteArrayOutputStream()
   private val reporter = new ConsoleReporter(new PrintStream(myOut))
-  def check(name: String, original: String, expected: String): Unit = {
+  def check(name: String, original: String, expected: String, verbose: Boolean = false): Unit = {
     test(name) {
       myOut.reset()
       reporter.reset()
@@ -22,7 +22,7 @@ class LinkHygieneSuite extends FunSuite with DiffAssertions {
         .default(root)
         .copy(reportRelativePaths = true, in = root, out = root)
       val links = DocumentLinks.fromGeneratedSite(settings, reporter)
-      LinkHygiene.lint(links, reporter)
+      LinkHygiene.lint(links, reporter, verbose)
       val obtained = fansi.Str(myOut.toString()).plainText
       assertNoDiffOrPrintExpected(obtained, expected)
     }
@@ -113,4 +113,20 @@ class LinkHygieneSuite extends FunSuite with DiffAssertions {
     """.stripMargin
   )
 
+  check(
+    "verbose",
+    """
+      |/a.md
+      |# Header 1
+      |[2](b.md#header)
+      |/b.md
+      |# Header 2
+    """.stripMargin,
+    """|warning: a.md:2:1: warning: Unknown link 'b.md#header'. isValidHeading=Set(b.md, b.md#header-2, a.md, a.md#header-1)
+       |[2](b.md#header)
+       |^^^^^^^^^^^^^^^^
+       |""".stripMargin,
+    verbose = true
+  )
+
 }