CommandsDocGenerator produces broken output since the case-app 2.x migration, and CI can't notice

[vimalaguti]

Summary

While working on #2076 I tried to regenerate docs/cli/reference.md the same way CI does:

sbt "frontend/runMain bloop.util.CommandsDocGenerator --out ../docs/cli/reference.md"

The regenerated file is visibly broken compared to the checked-in one. It looks like the generator has been producing broken output since the case-app 2.x migration (a077d7c, "Update to mainline case-app 2.x") — the checked-in docs/cli/reference.md predates that migration and was never regenerated since. Three related problems:

1. Command headings render as ## bloop List(about)

In frontend/src/main/scala/bloop/util/CommandsDocGenerator.scala, generateHTML interpolates the command name directly:

Commands.RawCommand.help.messages.map {
  case (commandName, messages) =>
    ...
    b ++= s"## `$progName $commandName$argsOption`"

With case-app 2.x, help.messages yields the command name as a Seq[String] rather than a String, so every heading renders as ## bloop List(about), ## bloop List(compile), etc.

2. (type: ...) annotations disappeared from option listings

The checked-in docs render options as:

--config-dir or -c (type: path?)

The current optionsMessage only renders option names and the @HelpMessage text, so regenerated docs lose all type information:

--config-dir or -c

3. CI runs the generator but never checks its output

.github/workflows/ci.yml runs:

frontend/runMain bloop.util.CommandsDocGenerator --test; \
frontend/runMain bloop.util.CommandsDocGenerator --out ../docs/cli/reference.md

--test only asserts the generation is non-empty, and the --out result is written into the CI workspace and then discarded — there is no diff check against the checked-in file and no commit step, so drift between the generator output and the committed docs/cli/reference.md goes undetected. That's how problems 1 and 2 stayed invisible: the website kept serving the last file generated before the migration.

Reproduction

On current main:

sbt "frontend/runMain bloop.util.CommandsDocGenerator --out ../docs/cli/reference.md"
git diff docs/cli/reference.md | head -20

shows -## bloop about / `+## `bloop List(about) style changes on every command section.

[tgodzik]

Thanks for reporting! I haven't looked into that one in a long while.