[native_assets_cli] Add paths to syntax views (#2107)

Bug: #1826

This PR adds the path that was navigated through the JSON to the syntax classes. This makes syntax errors more descriptive: `Unexpected value '123' for 'target_os'. Expected a String.` -> `Unexpected value '123' (int) for 'config.code.target_os'. Expected a String.`.

Because the data asset and code asset extensions don't know the internals of the base protocol extension, the extension points now expose both a `json` and a `jsonPath`. That path is then used to instantiate the syntax view of the extension, so it can give more precise error messages.

* For `CodeConfig` this comes naturally, it's a clean view.
* For `EncodedAsset` this is somewhat weird because it is half-used as value class: #2045

(The next PR will add a full syntax validation pass, at which point we should be able to address #2039.)

Author: dcharkes

pkgs/json_syntax_generator/lib/src/generator/helper_library.dart

@@ -6,17 +6,27 @@
 ///
 /// This simplifies the code generator.
 const helperLib = r'''
-extension on Map<String, Object?> {
+class JsonReader {
+  /// The JSON Object this reader is reading.
+  final Map<String, Object?> json;
+
+  /// The path traversed by readers of the surrounding JSON.
+  ///
+  /// Contains [String] property keys and [int] indices.
+  ///
+  /// This is used to give more precise error messages.
+  final List<Object> path;
+
+  JsonReader(this.json, this.path);
+
   T get<T extends Object?>(String key) {
-    final value = this[key];
+    final value = json[key];
     if (value is T) return value;
+    final pathString = _jsonPathToString([key]);
     if (value == null) {
-      throw FormatException('No value was provided for required key: $key');
+      throw FormatException("No value was provided for '$pathString'.");
     }
-    throw FormatException(
-      'Unexpected value \'$value\' for key \'.$key\'. '
-      'Expected a $T.',
-    );
+    throwFormatException(value, T, [key]);
   }
 
   List<T> list<T extends Object?>(String key) =>
@@ -29,14 +39,13 @@ extension on Map<String, Object?> {
       };
 
   /// [List.cast] but with [FormatException]s.
-  static List<T> _castList<T extends Object?>(List<Object?> list, String key) {
+  List<T> _castList<T extends Object?>(List<Object?> list, String key) {
+    var index = 0;
     for (final value in list) {
       if (value is! T) {
-        throw FormatException(
-          'Unexpected value \'$list\' (${list.runtimeType}) for key \'.$key\'. '
-          'Expected a ${List<T>}.',
-        );
+        throwFormatException(value, T, [key, index]);
       }
+      index++;
     }
     return list.cast();
   }
@@ -60,16 +69,13 @@ extension on Map<String, Object?> {
       };
 
   /// [Map.cast] but with [FormatException]s.
-  static Map<String, T> _castMap<T extends Object?>(
+  Map<String, T> _castMap<T extends Object?>(
     Map<String, Object?> map_,
-    String key,
+    String parentKey,
   ) {
-    for (final value in map_.values) {
+    for (final MapEntry(:key, :value) in map_.entries) {
       if (value is! T) {
-        throw FormatException(
-          'Unexpected value \'$map_\' (${map_.runtimeType}) for key \'.$key\'.'
-          'Expected a ${Map<String, T>}.',
-        );
+        throwFormatException(value, T, [parentKey, key]);
       }
     }
     return map_.cast();
@@ -79,7 +85,7 @@ extension on Map<String, Object?> {
 
   List<String> stringList(String key) => list<String>(key);
 
-  Uri path(String key) => _fileSystemPathToUri(get<String>(key));
+  Uri path$(String key) => _fileSystemPathToUri(get<String>(key));
 
   Uri? optionalPath(String key) {
     final value = get<String?>(key);
@@ -102,6 +108,23 @@ extension on Map<String, Object?> {
     return Uri.file(path);
   }
 
+  String _jsonPathToString(List<Object> pathEnding) =>
+      [...path, ...pathEnding].join('.');
+
+  Never throwFormatException(
+    Object? value,
+    Type expectedType,
+    List<Object> pathExtension,
+  ) {
+    final pathString = _jsonPathToString(pathExtension);
+    throw FormatException(
+      "Unexpected value '$value' (${value.runtimeType}) for '$pathString'. "
+      'Expected a $expectedType.',
+    );
+  }
+}
+
+extension on Map<String, Object?> {
   void setOrRemove(String key, Object? value) {
     if (value == null) {
       remove(key);

pkgs/json_syntax_generator/lib/src/generator/normal_class_generator.dart

@@ -72,7 +72,9 @@ class ClassGenerator {
     if (superclass != null) {
       buffer.writeln('''
 class $className extends $superclassName {
-  $className.fromJson(super.json) : super.fromJson();
+  $className.fromJson(super.json, {
+    super.path,
+  }) : super.fromJson();
 
   $className(${wrapBracesIfNotEmpty(constructorParams.join(', '))})
     : super(${superParams.join(',')}) 
@@ -102,9 +104,18 @@ class $className extends $superclassName {
 class $className {
   final Map<String, Object?> json;
 
-  $className.fromJson(this.json);
+  final List<Object> path;
 
-  $className(${wrapBracesIfNotEmpty(constructorParams.join(', '))}) : json = {} {
+  JsonReader get _reader => JsonReader(json, path);
+
+  $className.fromJson(this.json, {
+    this.path = const [],
+  });
+
+  $className(${wrapBracesIfNotEmpty(constructorParams.join(', '))})
+  : json = {},
+    path = const []
+  {
     ${constructorSetterCalls.join('\n    ')}
   }
 

pkgs/json_syntax_generator/lib/src/generator/property_generator.dart

@@ -95,7 +95,7 @@ class PropertyGenerator {
 
         buffer.writeln('''
 $dartType get $fieldName {
-  final jsonValue = json.get<$dartStringType>('$jsonKey'); $earlyReturn
+  final jsonValue = _reader.get<$dartStringType>('$jsonKey'); $earlyReturn
   return $classType.fromJson(jsonValue);
 }
 ''');
@@ -115,8 +115,8 @@ set $setterName($dartType value) {
         final jsonRead = required ? 'map\$' : 'optionalMap';
         buffer.writeln('''
 $dartType get $fieldName {
-  final jsonValue = json.$jsonRead('$jsonKey'); $earlyReturn
-  return $classType.fromJson(jsonValue);
+  final jsonValue = _reader.$jsonRead('$jsonKey'); $earlyReturn
+  return $classType.fromJson(jsonValue, path: [...path, '$jsonKey']);
 }
 ''');
         if (!property.isOverride) {
@@ -142,7 +142,7 @@ set $setterName($dartType value) {
     final fieldName = property.name;
 
     buffer.writeln('''
-$dartType get $fieldName => json.get<$dartType>('$jsonKey');
+$dartType get $fieldName => _reader.get<$dartType>('$jsonKey');
 
 set $setterName($dartType value) {
   json.setOrRemove('$jsonKey', value);
@@ -169,7 +169,7 @@ set $setterName($dartType value) {
       case MapDartType():
         buffer.writeln('''
 $dartType get $fieldName =>
-  json.optionalMap<${dartType.valueType}>('$jsonKey');
+  _reader.optionalMap<${dartType.valueType}>('$jsonKey');
 
 set $setterName($dartType value) {
   json.setOrRemove('$jsonKey', value);
@@ -181,17 +181,22 @@ set $setterName($dartType value) {
         final typeName = itemType.toString();
         buffer.writeln('''
 $dartType get $fieldName {
-  final map_ = json.optionalMap('$jsonKey');
-  if(map_ == null){
+  final jsonValue = _reader.optionalMap('$jsonKey');
+  if (jsonValue == null) {
     return null;
   }
-  return {
-    for (final MapEntry(:key, :value) in map_.entries)
-      key : [
-        for (final item in value as List<Object?>)
-          $typeName.fromJson(item as $jsonObjectDartType)
-      ],
-  };
+  final result = <String, List<Asset>>{};
+  for (final MapEntry(:key, :value) in jsonValue.entries) {
+    var index = 0;
+    result[key] = [
+      for (final item in value as List<Object?>)
+        $typeName.fromJson(
+          item as $jsonObjectDartType,
+          path: [...path, key, index++],
+        ),
+    ];
+  }
+  return result;
 }
 
 set $setterName($dartType value) {
@@ -214,7 +219,7 @@ set $setterName($dartType value) {
           case 'Object':
             if (valueType.isNullable) {
               buffer.writeln('''
-$dartType get $fieldName => json.optionalMap('$jsonKey');
+$dartType get $fieldName => _reader.optionalMap('$jsonKey');
 
 set $setterName($dartType value) {
   json.setOrRemove('$jsonKey', value);
@@ -251,8 +256,16 @@ set $setterName($dartType value) {
           throw UnimplementedError('Expected an optional property.');
         }
         buffer.writeln('''
-$dartType get $fieldName =>
-    json.optionalListParsed('$jsonKey', (e) => $typeName.fromJson(e as Map<String, Object?>));
+$dartType get $fieldName {
+  var index = 0;
+  return _reader.optionalListParsed(
+    '$jsonKey',
+    (e) => $typeName.fromJson(
+      e as Map<String, Object?>,
+      path: [...path, '$jsonKey', index++],
+    ),
+  );
+}
 
 set $setterName($dartType value) {
   if (value == null) {
@@ -273,7 +286,7 @@ set $setterName($dartType value) {
             final jsonRead = required ? 'stringList' : 'optionalStringList';
             final setter = setOrRemove(dartType, jsonKey);
             buffer.writeln('''
-$dartType get $fieldName => json.$jsonRead('$jsonKey');
+$dartType get $fieldName => _reader.$jsonRead('$jsonKey');
 
 set $setterName($dartType value) {
   $setter
@@ -288,7 +301,7 @@ set $setterName($dartType value) {
         final jsonRead = required ? 'pathList' : 'optionalPathList';
         final setter = setOrRemove(dartType, jsonKey, '.toJson()');
         buffer.writeln('''
-$dartType get $fieldName => json.$jsonRead('$jsonKey');
+$dartType get $fieldName => _reader.$jsonRead('$jsonKey');
 
 set $setterName($dartType value) {
   $setter
@@ -310,10 +323,10 @@ set $setterName($dartType value) {
   ) {
     final fieldName = property.name;
     final required = property.isRequired;
-    final jsonRead = required ? 'path' : 'optionalPath';
+    final jsonRead = required ? r'path$' : 'optionalPath';
     final setter = setOrRemove(dartType, jsonKey, '.toFilePath()');
     buffer.writeln('''
-$dartType get $fieldName => json.$jsonRead('$jsonKey');
+$dartType get $fieldName => _reader.$jsonRead('$jsonKey');
 
 set $setterName($dartType value) {
   $setter

pkgs/native_assets_cli/lib/src/code_assets/c_compiler_config.dart

@@ -37,19 +37,6 @@ final class CCompilerConfig {
     WindowsCCompilerConfig? windows,
   }) : _windows = windows;
 
-  /// Constructs a [CCompilerConfig] from the given [json].
-  ///
-  /// The json is expected to be valid encoding obtained via
-  /// [CCompilerConfig.toJson].
-  factory CCompilerConfig.fromJson(Map<String, Object?> json) =>
-      CCompilerConfigSyntax.fromSyntax(syntax.CCompilerConfig.fromJson(json));
-
-  /// The json representation of this [CCompilerConfig].
-  ///
-  /// The returned json can be used in [CCompilerConfig.fromJson] to
-  /// obtain a [CCompilerConfig] again.
-  Map<String, Object?> toJson() => toSyntax().json;
-
   @override
   bool operator ==(Object other) {
     if (other is! CCompilerConfig) {

pkgs/native_assets_cli/lib/src/code_assets/code_asset.dart

@@ -107,7 +107,10 @@ final class CodeAsset {
   factory CodeAsset.fromEncoded(EncodedAsset asset) {
     assert(asset.type == CodeAsset.type);
     final jsonMap = asset.encoding;
-    final syntaxNode = syntax.NativeCodeAsset.fromJson(jsonMap);
+    final syntaxNode = syntax.NativeCodeAsset.fromJson(
+      jsonMap,
+      path: asset.jsonPath ?? [],
+    );
     return CodeAsset._(
       id: syntaxNode.id,
       os: OSSyntax.fromSyntax(syntaxNode.os),

pkgs/native_assets_cli/lib/src/code_assets/config.dart

@@ -16,7 +16,7 @@ import 'syntax.g.dart' as syntax;
 /// to code assets (only available if code assets are supported).
 extension CodeAssetHookConfig on HookConfig {
   /// Code asset specific configuration.
-  CodeConfig get code => CodeConfig._fromJson(json);
+  CodeConfig get code => CodeConfig._fromJson(json, path);
 
   bool get buildCodeAssets => buildAssetTypes.contains(CodeAsset.type);
 }
@@ -41,8 +41,8 @@ extension CodeAssetLinkInput on LinkInputAssets {
 class CodeConfig {
   final syntax.CodeConfig _syntax;
 
-  CodeConfig._fromJson(Map<String, Object?> json)
-    : _syntax = syntax.Config.fromJson(json).code!;
+  CodeConfig._fromJson(Map<String, Object?> json, List<Object> path)
+    : _syntax = syntax.Config.fromJson(json, path: path).code!;
 
   /// The architecture the code code asset should be built for.
   ///