[messages] Use shared message parsing infrastructure in linter/tool.

Changes the logic in `pkg/linter/tool/machine.dart` and
`pkg/linter/tool/messages_info.dart` so that rather than parsing the
linter's `messages.yaml` file directly, it uses the shared
infrastructure in `pkg/analyzer_utilities` to read it.

This required adding a new `LintMessage` class to
`pkg/analyzer_utilities`, along with logic to validate and interpret
the linter message fields `categories`, `deprecatedDetails`, and
`state`. The corresponding logic in
`pkg/linter/tool/messages_info.dart` has been simplified accordingly.

This paves the way for upcoming `messages.yaml` format changes,
ensuring that those format changes won't break the logic in
`pkg/linter/tool/messages_info.dart`.

Change-Id: I6a6a696445a1fb599970ac4382d458fb31f1944d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/466442
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>

Author: stereotype441

pkg/analyzer/test/verify_diagnostics_test.dart

@@ -7,6 +7,7 @@ import 'package:analyzer/error/error.dart';
 import 'package:analyzer/utilities/package_config_file_builder.dart';
 import 'package:analyzer_testing/utilities/utilities.dart';
 import 'package:analyzer_utilities/analyzer_messages.dart';
+import 'package:analyzer_utilities/lint_messages.dart';
 import 'package:analyzer_utilities/messages.dart';
 import 'package:test/test.dart';
 import 'package:test_reflective_loader/test_reflective_loader.dart';

pkg/analyzer_utilities/lib/analyzer_messages.dart

@@ -110,6 +110,7 @@ const linterLintCodeInfo = DiagnosticClassInfo(
 /// Decoded messages from the analysis server's `messages.yaml` file.
 final List<AnalyzerMessage> analysisServerMessages = decodeAnalyzerMessagesYaml(
   analysisServerPkgPath,
+  decodeMessage: AnalyzerMessage.new,
   package: AnalyzerDiagnosticPackage.analysisServer,
 );
 
@@ -121,6 +122,7 @@ final String analysisServerPkgPath = normalize(
 /// Decoded messages from the analyzer's `messages.yaml` file.
 final List<AnalyzerMessage> analyzerMessages = decodeAnalyzerMessagesYaml(
   analyzerPkgPath,
+  decodeMessage: AnalyzerMessage.new,
   package: AnalyzerDiagnosticPackage.analyzer,
 );
 
@@ -132,21 +134,19 @@ final String analyzerPkgPath = normalize(
 /// The path to the `linter` package.
 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,
-  package: AnalyzerDiagnosticPackage.linter,
-);
-
 /// Decodes a YAML object (in analyzer style `messages.yaml` format) into a list
 /// of [AnalyzerMessage]s.
 ///
 /// If [allowLinterKeys], error checking logic will not reject key/value pairs
 /// that are used by the linter.
-List<AnalyzerMessage> decodeAnalyzerMessagesYaml(
+List<M> decodeAnalyzerMessagesYaml<M extends AnalyzerMessage>(
   String packagePath, {
-  bool allowLinterKeys = false,
+  required M Function(
+    MessageYaml, {
+    required AnalyzerCode analyzerCode,
+    required AnalyzerDiagnosticPackage package,
+  })
+  decodeMessage,
   required AnalyzerDiagnosticPackage package,
 }) {
   var path = join(packagePath, 'messages.yaml');
@@ -155,7 +155,7 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(
     sourceUrl: Uri.file(path),
   );
 
-  var result = <AnalyzerMessage>[];
+  var result = <M>[];
   if (yaml is! YamlMap) {
     throw LocatedError('root node is not a map', span: yaml.span);
   }
@@ -192,15 +192,14 @@ List<AnalyzerMessage> decodeAnalyzerMessagesYaml(
         );
       }
 
-      AnalyzerMessage message = MessageYaml.decode(
+      M message = MessageYaml.decode(
         key: keyNode,
         value: diagnosticValue,
         decoder: (messageYaml) {
           var analyzerCode = AnalyzerCode(snakeCaseName: diagnosticName);
-          return AnalyzerMessage(
+          return decodeMessage(
             messageYaml,
             analyzerCode: analyzerCode,
-            allowLinterKeys: allowLinterKeys,
             package: package,
           );
         },
@@ -281,9 +280,8 @@ class AliasMessage extends AnalyzerMessage {
     super.messageYaml, {
     required this.aliasFor,
     required super.analyzerCode,
-    required super.allowLinterKeys,
     required super.package,
-  }) : super._();
+  }) : super.internal();
 
   String get aliasForClass => aliasFor.split('.').first;
 
@@ -425,31 +423,27 @@ class AnalyzerMessage extends Message with MessageWithAnalyzerCode {
   factory AnalyzerMessage(
     MessageYaml messageYaml, {
     required AnalyzerCode analyzerCode,
-    required bool allowLinterKeys,
     required AnalyzerDiagnosticPackage package,
   }) {
     if (messageYaml.getOptionalString('aliasFor') case var aliasFor?) {
       return AliasMessage(
         messageYaml,
         aliasFor: aliasFor,
         analyzerCode: analyzerCode,
-        allowLinterKeys: allowLinterKeys,
         package: package,
       );
     } else {
-      return AnalyzerMessage._(
+      return AnalyzerMessage.internal(
         messageYaml,
         analyzerCode: analyzerCode,
-        allowLinterKeys: allowLinterKeys,
         package: package,
       );
     }
   }
 
-  AnalyzerMessage._(
+  AnalyzerMessage.internal(
     MessageYaml messageYaml, {
     required this.analyzerCode,
-    required bool allowLinterKeys,
     required this.package,
   }) : hasPublishedDocs = messageYaml.getBool('hasPublishedDocs'),
        type = messageYaml.get(
@@ -459,10 +453,6 @@ class AnalyzerMessage extends Message with MessageWithAnalyzerCode {
        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'});
-    }
   }
 }
 

pkg/analyzer_utilities/lib/lint_messages.dart

@@ -0,0 +1,122 @@
+// Copyright (c) 2025, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer_utilities/analyzer_messages.dart';
+import 'package:analyzer_utilities/located_error.dart';
+import 'package:pub_semver/pub_semver.dart';
+import 'package:yaml/yaml.dart';
+
+/// Decoded messages from the linter's `messages.yaml` file.
+final List<LintMessage> lintMessages = decodeAnalyzerMessagesYaml(
+  linterPkgPath,
+  decodeMessage: LintMessage.new,
+  package: AnalyzerDiagnosticPackage.linter,
+);
+
+enum LintCategory {
+  binarySize,
+  brevity,
+  documentationCommentMaintenance,
+  effectiveDart,
+  errorProne,
+  flutter,
+  languageFeatureUsage,
+  memoryLeaks,
+  nonPerformant,
+  pub,
+  publicInterface,
+  style,
+  unintentional,
+  unusedCode,
+  web;
+
+  static final Map<String, LintCategory> _stringToValue = {
+    for (var value in values) value.name: value,
+  };
+
+  static LintCategory? fromString(String s) => _stringToValue[s];
+}
+
+class LintMessage extends AnalyzerMessage {
+  final Set<LintCategory>? categories;
+
+  final String? deprecatedDetails;
+
+  final Map<LintStateName, Version>? state;
+
+  LintMessage(
+    super.messageYaml, {
+    required super.analyzerCode,
+    required super.package,
+  }) : categories = messageYaml.get(
+         'categories',
+         decode: decodeCategories,
+         ifAbsent: () => null,
+       ),
+       deprecatedDetails = messageYaml.getOptionalString('deprecatedDetails'),
+       state = messageYaml.get(
+         'state',
+         decode: decodeState,
+         ifAbsent: () => null,
+       ),
+       super.internal();
+
+  static Set<LintCategory> decodeCategories(YamlNode node) {
+    if (node is! YamlList) throw 'Must be a list';
+    var categoryList = node.nodes.map(
+      (element) =>
+          LocatedError.wrap(() => decodeCategory(element), span: element.span),
+    );
+    var categorySet = categoryList.toSet();
+    if (categorySet.length != categoryList.length) {
+      throw 'Duplicate entries in category list';
+    }
+    return categorySet;
+  }
+
+  static LintCategory decodeCategory(YamlNode node) => switch (node) {
+    YamlScalar(:String value) =>
+      LintCategory.fromString(value) ?? (throw 'Unknown lint category'),
+    _ => throw 'Must be a string',
+  };
+
+  static Map<LintStateName, Version> decodeState(YamlNode node) {
+    if (node is! YamlMap) throw 'Must be a map';
+    return {
+      for (var entry in node.nodes.entries)
+        LocatedError.wrap(
+          () => decodeStateName(entry.key as YamlScalar),
+          span: (entry.key as YamlScalar).span,
+        ): LocatedError.wrap(
+          () => decodeVersion(entry.value),
+          span: entry.value.span,
+        ),
+    };
+  }
+
+  static LintStateName decodeStateName(YamlNode node) => switch (node) {
+    YamlScalar(:String value) =>
+      LintStateName.fromString(value) ?? (throw 'Unknown lint state name'),
+    _ => throw 'Must be a string',
+  };
+
+  static Version decodeVersion(YamlNode node) => switch (node) {
+    YamlScalar(:String value) => Version.parse('$value.0'),
+    _ => throw 'Must be a string',
+  };
+}
+
+enum LintStateName {
+  experimental,
+  stable,
+  internal,
+  deprecated,
+  removed;
+
+  static final Map<String, LintStateName> _stringToValue = {
+    for (var value in values) value.name: value,
+  };
+
+  static LintStateName? fromString(String s) => _stringToValue[s];
+}

pkg/analyzer_utilities/lib/messages.dart

@@ -11,6 +11,7 @@ import 'dart:io';
 import 'package:analyzer_testing/package_root.dart' as pkg_root;
 import 'package:analyzer_utilities/analyzer_messages.dart';
 import 'package:analyzer_utilities/extensions/string.dart';
+import 'package:analyzer_utilities/lint_messages.dart';
 import 'package:analyzer_utilities/located_error.dart';
 import 'package:collection/collection.dart';
 import 'package:path/path.dart';

pkg/linter/tool/machine.dart

@@ -63,7 +63,9 @@ Future<String> getMachineListing(
       {
         'name': rule.name,
         'description': rule.description,
-        'categories': info.categories.toList(growable: false),
+        'categories': info.categories
+            .map((category) => category.name)
+            .toList(growable: false),
         'state': rule.state.label,
         'incompatible': rule.incompatibleRules,
         'sets': const [],