[messages] Rework message decoding and validation.

Reworks the message code generation logic so that the contents of the
`messages.yaml` files are (nearly) fully validated at the time they
are decoded.

The only fields that are not validated are those whose names are
passed to `MessageYaml.allowExtraKeys`. These fields are validated
elsewhere:

- The fields `bytes`, `declaration`, `exampleAllowMultipleReports`,
  `exampleAllowOtherCodes`, `experiments`, `expression`, `external`,
  `includeErrorContext`, `script`, and `statement`, when they appear
  in `pkg/_fe_analyzer_shared/messages.yaml` or
  `pkg/front_end/messages.yaml`. These fields are validated by the
  logic in `messages_suite.dart`, as part of verifying that the front
  end produces the expected diagnostics.

- The field `experiment`, when it appears in
  `pkg/analyzer/messages.yaml` or `pkg/linter/messages.yaml`. This
  field is validated by the logic in `verify_diagnostics_test.dart`,
  as part of verifying that the analyzer produces the expected
  diagnostics.

- The fields `categories`, `deprecatedDetails`, and `state`, when they
  appear in `pkg/linter/messages.yaml`. These fields are validated by
  the logic in `pkg/linter/tool/messages_info.dart`.

Change-Id: I6a6a69648bb3f5c3248489701bdf2ccc082a59ea
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/458067
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/analyzer/tool/messages/generate.dart

@@ -130,7 +130,7 @@ part of ${json.encode(file.parentLibrary)};
         var diagnosticCode = entry.key;
         var message = entry.value;
 
-        LocatedError.wrap(node: message.keyNode, () {
+        LocatedError.wrap(span: message.keySpan, () {
           if (message is! AliasMessage &&
               diagnosticClass.includeInDiagnosticCodeValues) {
             generatedCodes.add(diagnosticCode);

pkg/analyzer_utilities/lib/analyzer_messages.dart

@@ -189,11 +189,18 @@ final String linterPkgPath = normalize(join(pkg_root.packageRoot, 'linter'));
 /// Decoded messages from the linter's `messages.yaml` file.
 final List<AnalyzerMessage> lintMessages = decodeAnalyzerMessagesYaml(
   linterPkgPath,
+  allowLinterKeys: true,
 );
 
 /// Decodes a YAML object (in analyzer style `messages.yaml` format) into a list
 /// of [AnalyzerMessage]s.
-List<AnalyzerMessage> decodeAnalyzerMessagesYaml(String packagePath) {
+///
+/// If [allowLinterKeys], error checking logic will not reject key/value pairs
+/// that are used by the linter.
+List<AnalyzerMessage> decodeAnalyzerMessagesYaml(
+  String packagePath, {
+  bool allowLinterKeys = false,
+}) {
   var path = join(packagePath, 'messages.yaml');
   var yaml = loadYamlNode(
     File(path).readAsStringSync(),
@@ -202,22 +209,22 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(String packagePath) {
 
   var result = <AnalyzerMessage>[];
   if (yaml is! YamlMap) {
-    throw LocatedError('root node is not a map', node: yaml);
+    throw LocatedError('root node is not a map', span: yaml.span);
   }
   for (var classEntry in yaml.nodes.entries) {
     var keyNode = classEntry.key as YamlScalar;
     var className = keyNode.value;
     if (className is! String) {
       throw LocatedError(
         'non-string class key ${json.encode(className)}',
-        node: keyNode,
+        span: keyNode.span,
       );
     }
     var classValue = classEntry.value;
     if (classValue is! YamlMap) {
       throw LocatedError(
         'value associated with class key $className is not a map',
-        node: classValue,
+        span: classValue.span,
       );
     }
     for (var diagnosticEntry in classValue.nodes.entries) {
@@ -226,36 +233,40 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(String packagePath) {
       if (diagnosticName is! String) {
         throw LocatedError(
           'non-string diagnostic key ${json.encode(diagnosticName)}',
-          node: keyNode,
+          span: keyNode.span,
         );
       }
       var diagnosticValue = diagnosticEntry.value;
       if (diagnosticValue is! YamlMap) {
         throw LocatedError(
           'value associated with diagnostic is not a map',
-          node: diagnosticValue,
+          span: diagnosticValue.span,
         );
       }
 
-      AnalyzerMessage message = LocatedError.wrap(node: diagnosticValue, () {
-        var analyzerCode = AnalyzerCode(
-          diagnosticClass: DiagnosticClassInfo.byName(className),
-          snakeCaseName: diagnosticName,
-        );
-        return AnalyzerMessage.fromYaml(
-          diagnosticValue,
-          keyNode: keyNode,
-          analyzerCode: analyzerCode,
-        );
-      });
+      AnalyzerMessage message = MessageYaml.decode(
+        key: keyNode,
+        value: diagnosticValue,
+        decoder: (messageYaml) {
+          var analyzerCode = AnalyzerCode(
+            diagnosticClass: DiagnosticClassInfo.byName(className),
+            snakeCaseName: diagnosticName,
+          );
+          return AnalyzerMessage(
+            messageYaml,
+            analyzerCode: analyzerCode,
+            allowLinterKeys: allowLinterKeys,
+          );
+        },
+      );
       result.add(message);
 
       if (message case AliasMessage(:var aliasFor)) {
         var aliasForPath = aliasFor.split('.');
         if (aliasForPath.isEmpty) {
           throw LocatedError(
             "The 'aliasFor' value is empty",
-            node: diagnosticValue,
+            span: diagnosticValue.span,
           );
         }
         var node = yaml;
@@ -264,7 +275,7 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(String packagePath) {
           if (value is! YamlMap) {
             throw LocatedError(
               'No Map value at "$aliasFor"',
-              node: diagnosticValue,
+              span: diagnosticValue.span,
             );
           }
           node = value;
@@ -280,12 +291,12 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(String packagePath) {
 class AliasMessage extends AnalyzerMessage {
   String aliasFor;
 
-  AliasMessage._fromYaml(
-    super.yaml, {
+  AliasMessage(
+    super.messageYaml, {
     required this.aliasFor,
-    required super.keyNode,
     required super.analyzerCode,
-  }) : super._fromYaml();
+    required super.allowLinterKeys,
+  }) : super._();
 
   String get aliasForClass => aliasFor.split('.').first;
 
@@ -312,33 +323,38 @@ class AnalyzerMessage extends Message with MessageWithAnalyzerCode {
   @override
   final bool hasPublishedDocs;
 
-  factory AnalyzerMessage.fromYaml(
-    YamlMap yaml, {
-    required YamlScalar keyNode,
+  factory AnalyzerMessage(
+    MessageYaml messageYaml, {
     required AnalyzerCode analyzerCode,
+    required bool allowLinterKeys,
   }) {
-    if (yaml['aliasFor'] case var aliasFor?) {
-      return AliasMessage._fromYaml(
-        yaml,
-        aliasFor: aliasFor as String,
-        keyNode: keyNode,
+    if (messageYaml.getOptionalString('aliasFor') case var aliasFor?) {
+      return AliasMessage(
+        messageYaml,
+        aliasFor: aliasFor,
         analyzerCode: analyzerCode,
+        allowLinterKeys: allowLinterKeys,
       );
     } else {
-      return AnalyzerMessage._fromYaml(
-        yaml,
-        keyNode: keyNode,
+      return AnalyzerMessage._(
+        messageYaml,
         analyzerCode: analyzerCode,
+        allowLinterKeys: allowLinterKeys,
       );
     }
   }
 
-  AnalyzerMessage._fromYaml(
-    super.yaml, {
-    required super.keyNode,
+  AnalyzerMessage._(
+    MessageYaml messageYaml, {
     required this.analyzerCode,
-  }) : hasPublishedDocs =
-           yaml['hasPublishedDocs'] as bool? ??
-           (throw 'Missing key "hasPublishedDocs".'),
-       super.fromYaml();
+    required bool allowLinterKeys,
+  }) : hasPublishedDocs = messageYaml.getBool('hasPublishedDocs'),
+       super(messageYaml) {
+    // Ignore extra keys related to analyzer example-based tests.
+    messageYaml.allowExtraKeys({'experiment'});
+    if (allowLinterKeys) {
+      // Ignore extra keys understood by the linter.
+      messageYaml.allowExtraKeys({'categories', 'deprecatedDetails', 'state'});
+    }
+  }
 }