Add support for emitting usage as a JSON schema

- Vendor a copy of a library defining a JSON schema API which can output
  as a `Map<String, Object?>`.
- Add a `jsonSchema` getter on `ArgParser` which is similar to `usage`
  but outputs a schema instead of help text.

Clients can manually support a `--json-help` or similar argument in the
same way they support `--help`.

Author: natebosch

pkgs/args/lib/src/allow_anything_parser.dart

@@ -22,6 +22,10 @@ class AllowAnythingParser implements ArgParser {
   @override
   int? get usageLineLength => null;
 
+  @override
+  Map<String, Object?> get jsonSchema =>
+      const {'type': 'object', 'properties': {}};
+
   @override
   ArgParser addCommand(String name, [ArgParser? parser]) {
     throw UnsupportedError(

pkgs/args/lib/src/arg_parser.dart

@@ -6,6 +6,7 @@ import 'dart:collection';
 
 import 'allow_anything_parser.dart';
 import 'arg_results.dart';
+import 'json_schema.dart';
 import 'option.dart';
 import 'parser.dart';
 import 'usage.dart';
@@ -392,4 +393,48 @@ class ArgParser {
   /// Finds the option whose name or alias matches [name], or `null` if no
   /// option has that name or alias.
   Option? findByNameOrAlias(String name) => options[_aliases[name] ?? name];
+
+  Map<String, Object?> get jsonSchema {
+    final properties = <String, Schema>{};
+    final required = <String>[];
+    for (final option in _options.values) {
+      if (option.hide) continue;
+      var help = option.help;
+      final extras = <String>[];
+      if (option.defaultsTo != null) {
+        extras.add('defaults to "${option.defaultsTo}"');
+      }
+      if (option.allowed?.isNotEmpty ?? false) {
+        extras.add('allowed values: ${option.allowed?.join(', ')}');
+      }
+      if (extras.isNotEmpty) {
+        help = [
+          if (help != null) help,
+          ...extras,
+        ].join('\n');
+      }
+      final schema = switch (option.type) {
+        OptionType.flag => Schema.bool(
+            description: help,
+          ),
+        OptionType.single => Schema.string(
+            description: help,
+          ),
+        OptionType.multiple => Schema.list(
+            description: help,
+            items: Schema.string(),
+          ),
+        _ => throw StateError('Unhandled Option Type: ${option.type.name}')
+      };
+
+      if (option.mandatory) {
+        required.add(option.name);
+      }
+      properties[option.name] = schema;
+    }
+    return Schema.object(
+      properties: properties,
+      required: required,
+    ).asMap();
+  }
 }