Introduce tool info version 1

[cmcgee1024]

Fork the tool info version 0 to a new stable version 1. Introduce a new '--help-dump-tool-info-v1' flag that functions similarly to '--experimental-dump-help'. Create a new ToolInfoV1 to keep the new types for the new schema. Update the tool info serialization version to 1. Add a JSON schema for the version 1 tool info format.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[cmcgee1024]

@swift-ci please test

[rgoldberg]

@cmcgee1024 After Tool Info V1 has been merged in, do you want me to redo the completions script generation to use V1 instead of V0?

Or is someone else already tasked with that?

Should the migration be self explanatory or will there be any migration guide?

[cmcgee1024]

@cmcgee1024 After Tool Info V1 has been merged in, do you want me to redo the completions script generation to use V1 instead of V0?

The tool-info is practically identical between experimental and help-dump. Since the experimental flag remains in place, I think that existing integrations can safely rely on the v0 interface unless they have a reason to move off of it. This includes the shell completions, manual page, and docc markdown generators.

Should the migration be self explanatory or will there be any migration guide?

I expect that the migration will be self-explanatory with the same guide that explains the new tool-info v1 feature. Any suggestions of how to document this feature in SAP?

[rgoldberg]

Not sure exactly how to best document Tool Info.

I learned V0 because Rauhul had me review his V0 refactor of the Bash completion script generation, but that was shelved in favor of my then in-process pre-Tool-Info rewrite of the completion generators (merging that before the Tool Info transition was much easier).

I then migrated all the completions based on what I had learned from Rauhul's Bash migration for the older code.

I think it was all straightforward.

The only thing that didn't seem straightforward was why array values were allowed to be nil instead of making them non-optional, with empty arrays presumably able to accomplish the same thing. That would have slightly simplified the code.

Maybe there's a reason why nil must be allowed, but I am unaware of one (I don't know Swift in much depth). I never asked about it back then because I took the interface as a given, except when I ran into a few bugs / things that were left out, which I think I fixed, IIRC.

I'll probably migrate the completions after V1 has been merged, as long as no one else wants to do it, and as long as it isn't exceptionally onerous (which I doubt it would be).

Thanks for all the info & all your PRs.