Mention JSON format in dart2js args error message (#3414)

For `--define` arguments build_runner will attempt a JSON parse, and
treat anything with a format error as a `String`.
Parsing as JSON allows for structured content, similar to what can be
added in `build.yaml`. Silently falling back to the input as a string
avoids requiring extra quotes for the majority of simple options.

When the JSON decode fails unexpectedly, the error message can be
confusing and does not point to the problem. It's not easy to
distinguish between a `build.yaml` with a String value (that never would
be parsed as JSON) or command line argument, so we cannot tell for sure
if JSON formatting is the problem. The best we can do is point out that
it may have failed to parse.

Remove the name of the argument from the message, it is already present
in the `ArgumentError.toString()`.

build_web_compilers/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.2.8-dev
+
+- Mention JSON formatting in error message about dart2js args.
+
 ## 3.2.7
 
 - Migrate off deprecated analyzer apis.

build_web_compilers/lib/src/web_entrypoint_builder.dart

@@ -99,8 +99,11 @@ class WebEntrypointBuilder implements Builder {
     }
 
     if (options.config[_dart2jsArgsOption] is! List) {
-      throw ArgumentError.value(options.config[_dart2jsArgsOption],
-          _dart2jsArgsOption, 'Expected a list for $_dart2jsArgsOption.');
+      var message = options.config[_dart2jsArgsOption] is String
+          ? 'There may have been a failure decoding as JSON, expected a list'
+          : 'Expected a list';
+      throw ArgumentError.value(
+          options.config[_dart2jsArgsOption], _dart2jsArgsOption, message);
     }
     var dart2JsArgs = (options.config[_dart2jsArgsOption] as List?)
             ?.map((arg) => '$arg')

build_web_compilers/pubspec.yaml

@@ -1,5 +1,5 @@
 name: build_web_compilers
-version: 3.2.7
+version: 3.2.8-dev
 description: Builder implementations wrapping the dart2js and DDC compilers.
 repository: https://github.com/dart-lang/build/tree/master/build_web_compilers