Add option to write diagnostics to a file to provide more information to tools

[d-ronnqvist]

Bug/issue #, if applicable: rdar://105181169

Summary

This PR adds the option to write diagnostics to a file to have the ability to provide more diagnostic information to tools than what's available in the command line output format.

To request the diagnostics file output, tools can pass the new --diagnostics-file option.

To know what version of the docc executable supports the diagnostics file output, DocC now has a "features.json" file with the same format as Swift. This file is installed at usr/share/docc/features.json when running the "install" action in build-script-helper.py.

This PR also separates the formatting intended for tools and formatting intended for people in DiagnosticConsoleWriter. As part of this separation, behavior that was implicitly ties to this formatting is deprecated in favor of explicit formatting.

With the future possibility of making a common line output format for people that isn't limited by tool parsing, the goal is to always present diagnosis solutions in some form. To prepare for this, the --emit-fixits flag is renamed to --ide-console-output. (If you have feedback on that flag name, now is a good time.)

Dependencies

None

Testing

With any documentation project that produce some warnings (for example the test bundle at "Tests/SwiftDocCTests/Test Bundles/TestBundle.docc")

• Build documentation passing the --emit-fixits flag:

  swift run docc convert ./Tests/SwiftDocCTests/Test\ Bundles/TestBundle.docc --emit-fixits
  

  The common line output should be formatted for tools to parse (including fixits)

• Build documentation passing the --ide-console-output flag:

  swift run docc convert ./Tests/SwiftDocCTests/Test\ Bundles/TestBundle.docc --ide-console-output
  

  The common line output should be formatted for tools to parse (including fixits)

• Build documentation passing the path to write a diagnostics file to:

  swift run docc convert ./Tests/SwiftDocCTests/Test\ Bundles/TestBundle.docc --diagnostics-file ./test-diagnostics.json
  

  The common line output should be formatted for tools to parse (including fixits)
  The diagnostics file should list all the emitted diagnostics with information about their related solutions and notes.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[franklinsch]

nit: Are we expecting diagnostics in this format to only be used by IDEs, or are there broader applications? If so, maybe there is a term that describes what the format provides rather than what we expect to use it for. For example "RichDiagnosticConsoleFormater

[d-ronnqvist]

It's intended to be parsed by IDEs and other tools or scripts who are interacting with the docc executable. The format (which is the same as today) contains some general information about the diagnostics in an easily parseable format but doesn't provide the full diagnostic information.

I think once we improve the default diagnostic format (#496) there shouldn't be many use cases for this format other than tools/scripts who don't need the full details of the diagnostic file.

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

I verified the features.json install location with swiftlang/swift#64038

$ find usr -name "features.json"
usr/share/clang/features.json
usr/share/swift/features.json
usr/share/docc/features.json