[front_end] Make a script to add "parameters" entries to messages.yaml.

The new script, `pkg/front_end/tool/add_parameters_to_messages.dart`,
iterates through all the entries in `pkg/front_end/messages.yaml`. For
each parameter used in a `problemMessage` or `correctionMessage`, it
generates a `parameters` entry, with the appropriate parameter name
and type, and a documentation placeholder ("undocumented"). Future CLs
will fill in documentation strings and rename the parameters as needed
for clarity.

For messages that don't take any parameters, the script adds
`parameters: none` to the YAML source.

To make the script easier to write, a `yamlNode` field is added to the
`ErrorCodeInfo` class; this makes it easy for the script to find the
location in the YAML file where message is declared, so that it can
add the `parameters` entry.

Change-Id: I6a6a6964cbbd01bbe0cf7dbb1ef7944e0a61f6e9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/448250
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/analyzer/tool/messages/error_code_info.dart

@@ -9,7 +9,7 @@ import 'package:analyzer_testing/package_root.dart' as pkg_root;
 import 'package:analyzer_utilities/messages.dart';
 import 'package:analyzer_utilities/tools.dart';
 import 'package:path/path.dart';
-import 'package:yaml/yaml.dart' show loadYaml;
+import 'package:yaml/yaml.dart' show loadYaml, YamlMap;
 
 const codesFile = GeneratedErrorCodeFile(
   path: 'analyzer/lib/src/error/codes.g.dart',
@@ -212,7 +212,7 @@ Map<String, Map<String, AnalyzerErrorCodeInfo>> decodeAnalyzerMessagesYaml(
         );
       }
       var errorValue = errorEntry.value;
-      if (errorValue is! Map<Object?, Object?>) {
+      if (errorValue is! YamlMap) {
         problem(
           'value associated with error $className.$errorName is not a '
           'map',
@@ -296,7 +296,7 @@ class AliasErrorCodeInfo extends AnalyzerErrorCodeInfo {
 /// In-memory representation of error code information obtained from the
 /// analyzer's `messages.yaml` file.
 class AnalyzerErrorCodeInfo extends ErrorCodeInfo {
-  factory AnalyzerErrorCodeInfo.fromYaml(Map<Object?, Object?> yaml) {
+  factory AnalyzerErrorCodeInfo.fromYaml(YamlMap yaml) {
     if (yaml['aliasFor'] case var aliasFor?) {
       return AliasErrorCodeInfo._fromYaml(yaml, aliasFor: aliasFor as String);
     } else {

pkg/analyzer_utilities/lib/messages.dart

@@ -9,7 +9,7 @@ import 'package:analyzer_testing/package_root.dart' as pkg_root;
 import 'package:analyzer_utilities/extensions/string.dart';
 import 'package:analyzer_utilities/tools.dart';
 import 'package:path/path.dart';
-import 'package:yaml/yaml.dart' show loadYaml;
+import 'package:yaml/yaml.dart' show loadYaml, YamlMap;
 
 const Map<String, String> severityEnumNames = <String, String>{
   'CONTEXT': 'context',
@@ -105,7 +105,7 @@ Map<String, FrontEndErrorCodeInfo> decodeCfeMessagesYaml(Object? yaml) {
       problem('non-string error key ${json.encode(errorName)}');
     }
     var errorValue = entry.value;
-    if (errorValue is! Map<Object?, Object?>) {
+    if (errorValue is! YamlMap) {
       problem('value associated with error $errorName is not a map');
     }
     try {
@@ -119,8 +119,10 @@ Map<String, FrontEndErrorCodeInfo> decodeCfeMessagesYaml(Object? yaml) {
 
 /// Loads front end messages from the front end's `messages.yaml` file.
 Map<String, FrontEndErrorCodeInfo> _loadFrontEndMessages() {
+  var path = join(frontEndPkgPath, 'messages.yaml');
   Object? messagesYaml = loadYaml(
-    File(join(frontEndPkgPath, 'messages.yaml')).readAsStringSync(),
+    File(path).readAsStringSync(),
+    sourceUrl: Uri.file(path),
   );
   return decodeCfeMessagesYaml(messagesYaml);
 }
@@ -302,6 +304,13 @@ abstract class ErrorCodeInfo {
   /// hasn't been translated from the old placeholder format yet.
   final List<ErrorCodeParameter>? parameters;
 
+  /// The raw YAML node that this `ErrorCodeInfo` was parsed from, or `null` if
+  /// this `ErrorCodeInfo` was created without reference to a raw YAML node.
+  ///
+  /// This exists to make it easier for automated scripts to edit the YAML
+  /// source.
+  final YamlMap? yamlNode;
+
   ErrorCodeInfo({
     this.comment,
     this.documentation,
@@ -314,6 +323,7 @@ abstract class ErrorCodeInfo {
     this.previousName,
     this.removedIn,
     this.parameters,
+    this.yamlNode,
   }) {
     for (var MapEntry(:key, :value) in {
       'problemMessage': problemMessage,
@@ -330,7 +340,7 @@ abstract class ErrorCodeInfo {
   }
 
   /// Decodes an [ErrorCodeInfo] object from its YAML representation.
-  ErrorCodeInfo.fromYaml(Map<Object?, Object?> yaml)
+  ErrorCodeInfo.fromYaml(YamlMap yaml)
     : this(
         comment: yaml['comment'] as String?,
         correctionMessage: _decodeMessage(yaml['correctionMessage']),
@@ -344,6 +354,7 @@ abstract class ErrorCodeInfo {
         removedIn: yaml['removedIn'] as String?,
         previousName: yaml['previousName'] as String?,
         parameters: _decodeParameters(yaml['parameters']),
+        yamlNode: yaml,
       );
 
   /// If this error is no longer reported and
@@ -757,7 +768,7 @@ class FrontEndErrorCodeInfo extends ErrorCodeInfo {
   /// severity.
   final String? cfeSeverity;
 
-  FrontEndErrorCodeInfo.fromYaml(Map<Object?, Object?> yaml)
+  FrontEndErrorCodeInfo.fromYaml(YamlMap yaml)
     : analyzerCode = _decodeAnalyzerCode(yaml['analyzerCode']),
       index = _decodeIndex(yaml['index']),
       cfeSeverity = _decodeSeverity(yaml['severity']),

pkg/front_end/pubspec.yaml

@@ -23,9 +23,11 @@ dependencies:
 # Use 'any' constraints here; we get our versions from the DEPS file.
 dev_dependencies:
   analyzer: any
+  analyzer_plugin: any
   analyzer_utilities: any
   args: any
   build_integration: any
+  collection: any
   compiler: any
   dart_style: any
   dart2wasm: any

pkg/front_end/tool/add_parameters_to_messages.dart

@@ -0,0 +1,84 @@
+// 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.
+
+/// This is a temporary utility script that modifies
+/// `pkg/front_end/messages.yaml`, inserting explicit "parameters" declarations
+/// based on the existing parameter placeholders.
+///
+/// For example, a message like this:
+/// ```
+/// SwitchExpressionNotSubtype:
+///   problemMessage: >
+///     Type '#type' of the case expression is not a subtype of type '#type2'
+///     of this switch expression.
+///   ...
+/// ```
+///
+/// will get converted into:
+/// ```
+/// SwitchExpressionNotSubtype:
+///   parameters:
+///     Type type: undocumented
+///     Type type2: undocumented
+///   problemMessage: >
+///     Type '#type' of the case expression is not a subtype of type '#type2'
+///     of this switch expression.
+///   ...
+/// ```
+///
+/// Messages that don't take any parameters will have an entry added of the form
+/// `parameters: none`.
+library;
+
+import 'dart:io';
+
+import 'package:analyzer_plugin/protocol/protocol_common.dart';
+import 'package:analyzer_utilities/messages.dart';
+import 'package:collection/collection.dart';
+
+void main() {
+  var edits = <Uri, List<SourceEdit>>{};
+
+  for (var message in frontEndMessages.values) {
+    if (message.parameters != null) {
+      // Message already converted.
+      continue;
+    }
+    var parameters = <String, String>{};
+    for (var value in [message.problemMessage, message.correctionMessage]) {
+      if (value == null) continue;
+      for (Match match in placeholderPattern.allMatches(value)) {
+        var parsedPlaceholder = ParsedPlaceholder.fromMatch(match);
+        var type = parsedPlaceholder.templateParameterType.messagesYamlName;
+        var name = parsedPlaceholder.name;
+        parameters['$type $name'] = 'undocumented';
+      }
+    }
+    List<String> linesToAdd;
+    if (parameters.isEmpty) {
+      linesToAdd = ['parameters: none'];
+    } else {
+      linesToAdd = [
+        'parameters:',
+        for (var entry in parameters.entries) '  ${entry.key}: ${entry.value}',
+      ];
+    }
+    var span = message.yamlNode!.span;
+    var indent = ' ' * span.start.column;
+    var text = linesToAdd.map((line) => '$line\n$indent').join();
+    (edits[span.sourceUrl!] ??= []).add(SourceEdit(span.start.offset, 0, text));
+  }
+
+  for (var entry in edits.entries) {
+    var file = File(entry.key.toFilePath());
+    stdout.write('Updating ${file.path}...');
+    file.writeAsStringSync(
+      SourceEdit.applySequence(
+        file.readAsStringSync(),
+        entry.value..sortBy((e) => -e.offset),
+      ),
+    );
+    stdout.writeln('done!');
+  }
+}