From b56fa3bba0bbcebc3cc3322e089c87ef4e469d71 Mon Sep 17 00:00:00 2001
From: Nate Bosch <nbosch@google.com>
Date: Mon, 9 Jun 2025 23:26:45 +0000
Subject: [PATCH] Add --json-help argument

Add a hidden `--json-help` argument which writes the usage information
in JSON Schema format.
---
 pkgs/test_core/lib/src/executable.dart              |  5 +++++
 pkgs/test_core/lib/src/runner/configuration.dart    | 13 +++++++++++++
 .../lib/src/runner/configuration/args.dart          |  4 ++++
 pkgs/test_core/pubspec.yaml                         |  7 +++++++
 4 files changed, 29 insertions(+)

diff --git a/pkgs/test_core/lib/src/executable.dart b/pkgs/test_core/lib/src/executable.dart
index eeefd161c..62e0ff128 100644
--- a/pkgs/test_core/lib/src/executable.dart
+++ b/pkgs/test_core/lib/src/executable.dart
@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'dart:async';
+import 'dart:convert';
 import 'dart:io';
 
 import 'package:async/async.dart';
@@ -81,6 +82,10 @@ Future<void> _execute(List<String> args) async {
     _printUsage();
     return;
   }
+  if (configuration.jsonHelp) {
+    stdout.write(jsonEncode(Configuration.jsonSchema));
+    return;
+  }
 
   if (configuration.version) {
     var version = testVersion;
diff --git a/pkgs/test_core/lib/src/runner/configuration.dart b/pkgs/test_core/lib/src/runner/configuration.dart
index 8ba4aa810..c6cfab05a 100644
--- a/pkgs/test_core/lib/src/runner/configuration.dart
+++ b/pkgs/test_core/lib/src/runner/configuration.dart
@@ -42,10 +42,16 @@ class Configuration {
   /// The usage string for the command-line arguments.
   static String get usage => args.usage;
 
+  static Map<String, Object?> get jsonSchema => args.jsonSchema;
+
   /// Whether `--help` was passed.
   bool get help => _help ?? false;
   final bool? _help;
 
+  /// Whether `--json-help` was passed.
+  bool get jsonHelp => _jsonHelp ?? false;
+  final bool? _jsonHelp;
+
   /// Custom HTML template file.
   final String? customHtmlTemplatePath;
 
@@ -248,6 +254,7 @@ class Configuration {
 
   factory Configuration(
       {required bool? help,
+      bool? jsonHelp,
       required String? customHtmlTemplatePath,
       required bool? version,
       required bool? pauseAfterLoad,
@@ -300,6 +307,7 @@ class Configuration {
     var chosenPresetSet = chosenPresets?.toSet();
     var configuration = Configuration._(
         help: help,
+        jsonHelp: jsonHelp,
         customHtmlTemplatePath: customHtmlTemplatePath,
         version: version,
         pauseAfterLoad: pauseAfterLoad,
@@ -731,6 +739,7 @@ class Configuration {
   /// Unlike [Configuration.new], this assumes [presets] is already resolved.
   Configuration._(
       {required bool? help,
+      required bool? jsonHelp,
       required this.customHtmlTemplatePath,
       required bool? version,
       required bool? pauseAfterLoad,
@@ -759,6 +768,7 @@ class Configuration {
       required Iterable<Pattern>? globalPatterns,
       required SuiteConfiguration? suiteDefaults})
       : _help = help,
+        _jsonHelp = jsonHelp,
         _version = version,
         _pauseAfterLoad = pauseAfterLoad,
         _debug = debug,
@@ -814,6 +824,7 @@ class Configuration {
         suiteDefaults: suiteConfig,
         globalPatterns: null,
         help: null,
+        jsonHelp: null,
         customHtmlTemplatePath: null,
         version: null,
         pauseAfterLoad: null,
@@ -911,6 +922,7 @@ class Configuration {
 
     var result = Configuration._(
         help: other._help ?? _help,
+        jsonHelp: other._jsonHelp ?? _jsonHelp,
         customHtmlTemplatePath:
             other.customHtmlTemplatePath ?? customHtmlTemplatePath,
         version: other._version ?? _version,
@@ -1006,6 +1018,7 @@ class Configuration {
       Iterable<String>? addTags}) {
     var config = Configuration._(
         help: help ?? _help,
+        jsonHelp: _jsonHelp,
         customHtmlTemplatePath:
             customHtmlTemplatePath ?? this.customHtmlTemplatePath,
         version: version ?? _version,
diff --git a/pkgs/test_core/lib/src/runner/configuration/args.dart b/pkgs/test_core/lib/src/runner/configuration/args.dart
index e981bedc3..eabf1975b 100644
--- a/pkgs/test_core/lib/src/runner/configuration/args.dart
+++ b/pkgs/test_core/lib/src/runner/configuration/args.dart
@@ -26,6 +26,7 @@ final ArgParser _parser = (() {
 
   parser.addFlag('help',
       abbr: 'h', negatable: false, help: 'Show this usage information.');
+  parser.addFlag('json-help', negatable: false, hide: true);
   parser.addFlag('version',
       negatable: false, help: 'Show the package:test version.');
 
@@ -183,6 +184,8 @@ final ArgParser _parser = (() {
 /// The usage string for the command-line arguments.
 String get usage => _parser.usage;
 
+Map<String, Object?> get jsonSchema => _parser.jsonSchema;
+
 /// Parses the configuration from [args].
 ///
 /// Throws a [FormatException] if [args] are invalid.
@@ -316,6 +319,7 @@ class _Parser {
 
     return Configuration(
         help: _ifParsed('help'),
+        jsonHelp: _ifParsed('json-help'),
         version: _ifParsed('version'),
         verboseTrace: _ifParsed('verbose-trace'),
         chainStackTraces: _ifParsed('chain-stack-traces'),
diff --git a/pkgs/test_core/pubspec.yaml b/pkgs/test_core/pubspec.yaml
index 78cc8ea24..c386e69fd 100644
--- a/pkgs/test_core/pubspec.yaml
+++ b/pkgs/test_core/pubspec.yaml
@@ -34,3 +34,10 @@ dependencies:
 
 dev_dependencies:
   test: any
+
+dependency_overrides:
+  args:
+    git:
+      url: https://github.com/dart-lang/core.git
+      path: pkgs/args
+      ref: json-schema