Verbose option and always log Elm errors to console

[absynce]

Thanks for making elm-doc-preview! I love it and use it all the time at work for application documentation. 💌

I use it in server mode locally, and run elm-doc-preview --output /dev/null in CI. However, when running locally, if I don't open the docs, I don't know if there's an error. I use Simon Lydell's run-pty to run all of our tools in parallel. With elm-doc-preview, sometimes I don't get the feedback until CI runs. I'd like to have the errors on the console, so I could set the status in run-pty according to the output.

Without logging that there's an error, it's always green:

I might be able to add a separate process that runs elm-doc-preview --output /dev/null, but that seems wasteful and redundant.

Instead, I added a console.error if there's an error, and a --verbose option that will display the error details to the console when in server mode.

Without --verbose

With --verbose

I also considered that some of the port stubbing details might make sense to put behind the --verbose flag, too. We have a lot of them at work, and it floods the output.

Please let me know what you think.

[rlefevre]

Thank you, this looks good.

My only comment is that there was already an implicit verbose option in buildDocs, enabled when --output was used.
So it's a little weird to have a verbose flag that is only used in server mode.

See this call to buildDocs with verbose always set to true:
https://github.com/absynce/elm-doc-preview/blob/0ade08c1b0ee2063e696a2da4d21f1c52d42d232/lib/elm-doc-server.ts#L914

That said changing the behavior in --output mode could change the behavior of existing CI, so I'm not sure what's the best path here.

As a consequence, the flag description might need to be slightly adapted too.

[absynce]

Good points! I didn't change output mode behavior because showing errors on the console in that case always seems useful.

How's this for an updated flag description?

verbose console output (including documentation errors in server mode, output mode always shows errors)

[absynce]

After using this for a bit, I realized there wasn't a clear distinction when it succeeded again (I couldn't make run-pty go green again). So I also added an info log when the build succeeds:

✅ Documentation build succeeded!

[absynce]

Actually, what if we always showed documentation error details in the console output, regardless of mode?

The verbose flag makes more sense to me for things like stubbing ports. But I don't necessarily want to see stubbing details even when I want to see the errors.

I'll try it and see how it goes.

[absynce]

I originally used verbose to display errors because that's what the argument was in buildDocs that changed that behavior, but I think it would be nice to always show errors in the console. And I like not having all the stubbing details.

Before and now with --verbose:

There are 50+ more lines of "stubbing ... port".

After and without --verbose:

In both cases, I see the error details, but I also don't get the barrage of port stubbing details unless I add --verbose.

[absynce]

I added this exception handler (14f0e05) after I discovered an issue during our CI builds. We were running elm-doc-preview in parallel with elm-test and elm-review.

It would fail sometimes with a vague error about parsing:

SyntaxError: Unexpected token '+', "+---------"... is not valid JSON

I found it was trying to parse this:

+-------------------------------------------------------------------------------
|  Corrupt File: /root/.elm/0.19.1/packages/elm-explorations/test/2.2.0/artifacts.dat
|   Byte Offset: 101307
|       Message: Could not map value 17 to Bool
|
| Please report this to https://github.com/elm/compiler/issues
| Trying to continue anyway.
+-------------------------------------------------------------------------------

Now, we handle and log it! Elm will gracefully recover, and elm-doc-preview will exit successfully in output mode. 🎉

[absynce]

Should we change how we determine build success? Currently, if it encounters the corrupt file stderr, "✅ Documentation build succeeded!" won't be logged. Maybe this should be moved to after the docs are successfully parsed.