update the generator to emit formatted files (#1020)

Author: devoncarew

.github/workflows/dart.yml

@@ -80,7 +80,7 @@ jobs:
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:benchmarks;commands:format-command_0-command_1-analyze_0"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:benchmarks;commands:format_0-command_0-command_1-analyze_0"
           restore-keys: |
             os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:benchmarks
             os:ubuntu-latest;pub-cache-hosted;sdk:dev
@@ -122,7 +122,7 @@ jobs:
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protobuf;commands:format-analyze_0"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protobuf;commands:format_0-analyze_0"
           restore-keys: |
             os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protobuf
             os:ubuntu-latest;pub-cache-hosted;sdk:dev
@@ -149,14 +149,14 @@ jobs:
         if: "always() && steps.protobuf_pub_upgrade.conclusion == 'success'"
         working-directory: protobuf
   job_005:
-    name: "format_analyze; linux; Dart dev; PKG: protoc_plugin; `dart format --output=none --set-exit-if-changed .`, `./../tool/setup.sh`, `make protos`, `dart analyze --fatal-infos`"
+    name: "format_analyze; linux; Dart dev; PKG: protoc_plugin; `dart format --output=none --set-exit-if-changed lib`, `./../tool/setup.sh`, `make protos`, `dart analyze --fatal-infos`"
     runs-on: ubuntu-latest
     steps:
       - name: Cache Pub hosted dependencies
         uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684
         with:
           path: "~/.pub-cache/hosted"
-          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protoc_plugin;commands:format-command_0-command_2-analyze_0"
+          key: "os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protoc_plugin;commands:format_1-command_0-command_2-analyze_0"
           restore-keys: |
             os:ubuntu-latest;pub-cache-hosted;sdk:dev;packages:protoc_plugin
             os:ubuntu-latest;pub-cache-hosted;sdk:dev
@@ -174,8 +174,8 @@ jobs:
         run: dart pub upgrade
         if: "always() && steps.checkout.conclusion == 'success'"
         working-directory: protoc_plugin
-      - name: "protoc_plugin; dart format --output=none --set-exit-if-changed ."
-        run: "dart format --output=none --set-exit-if-changed ."
+      - name: "protoc_plugin; dart format --output=none --set-exit-if-changed lib"
+        run: "dart format --output=none --set-exit-if-changed lib"
         if: "always() && steps.protoc_plugin_pub_upgrade.conclusion == 'success'"
         working-directory: protoc_plugin
       - name: protoc_plugin; ./../tool/setup.sh

protoc_plugin/CHANGELOG.md

@@ -1,5 +1,7 @@
-## 22.4.1-wip
+## 22.5.0-wip
 
+* Generated files are now formatted using the Dart formatter. The code is
+  formatted using the min. SDK for `package:protoc_plugin`; currently `3.7.0`.
 * Minimum SDK dependency bumped from 3.6.0 to 3.7.0. ([#1024])
 
 [#1024]: https://github.com/google/protobuf.dart/pull/1024

protoc_plugin/Makefile

@@ -89,14 +89,11 @@ $(TEST_PROTO_LIBS): $(PLUGIN_SRC) $(TEST_PROTO_SRCS)
 		--plugin=protoc-gen-dart=$(realpath $(PLUGIN_PATH))\
 		$(TEST_PROTO_SRCS)
 
-	dart format $(TEST_PROTO_DIR)
-
 update-pregenerated: $(PLUGIN_PATH) $(PREGENERATED_SRCS)
 	protoc --dart_out=lib/src/gen \
 		-Iprotos \
 		--plugin=protoc-gen-dart=$(realpath $(PLUGIN_PATH)) $(PREGENERATED_SRCS)
 	find lib/src/gen -name '*.pbjson.dart' -delete
-	dart format lib/src/gen
 
 protos: $(PLUGIN_PATH) $(TEST_PROTO_LIBS)
 

protoc_plugin/lib/indenting_writer.dart

@@ -4,6 +4,7 @@
 
 import 'dart:collection';
 
+import 'src/formatter.dart' as formatter;
 import 'src/gen/google/protobuf/descriptor.pb.dart';
 
 /// Specifies code locations where metadata annotations should be attached and
@@ -22,6 +23,9 @@ class NamedLocation {
 
 /// A buffer for writing indented source code.
 class IndentingWriter {
+  final String? fileName;
+  final bool generateMetadata;
+
   final StringBuffer _buffer = StringBuffer();
   final GeneratedCodeInfo sourceLocationInfo = GeneratedCodeInfo();
 
@@ -30,12 +34,11 @@ class IndentingWriter {
   // After writing any chunk, _previousOffset is the size of everything that was
   // written to the buffer before the latest call to print or addBlock.
   int _previousOffset = 0;
-  final String? _sourceFile;
 
   // Named text sections to write at the end of the file.
   final Map<String, String> _suffixes = SplayTreeMap();
 
-  IndentingWriter({String? filename}) : _sourceFile = filename;
+  IndentingWriter({this.fileName, this.generateMetadata = false});
 
   /// Appends a string indented to the current level.
   /// (Indentation will be added after newline characters where needed.)
@@ -138,18 +141,27 @@ class IndentingWriter {
     _suffixes[suffixKey] = text;
   }
 
-  @override
-  String toString() {
+  /// Emit the generated source.
+  ///
+  /// This is safe to call multiple times.
+  String emitSource({required bool format}) {
     if (_suffixes.isNotEmpty) {
-      // TODO: We may want to introduce the notion of closing the writer.
       println('');
       for (final key in _suffixes.keys) {
         println(_suffixes[key]!);
       }
       _suffixes.clear();
     }
 
-    return _buffer.toString();
+    var source = _buffer.toString();
+
+    // We don't always want to format the source (for example, we don't want to
+    // format if we're creating annotated locations of source elements).
+    if (format) {
+      source = formatter.format(source);
+    }
+
+    return source;
   }
 
   /// Writes part of a line of text.
@@ -175,16 +187,15 @@ class IndentingWriter {
   /// string that was passed to the previous [print]. Name should be the string
   /// that was written to file.
   void _addAnnotation(List<int> fieldPath, String name, int start) {
-    if (_sourceFile == null) {
-      return;
+    if (generateMetadata) {
+      final annotation =
+          GeneratedCodeInfo_Annotation()
+            ..path.addAll(fieldPath)
+            ..sourceFile = fileName!
+            ..begin = _previousOffset + start
+            ..end = _previousOffset + start + name.length;
+      sourceLocationInfo.annotation.add(annotation);
     }
-    final annotation =
-        GeneratedCodeInfo_Annotation()
-          ..path.addAll(fieldPath)
-          ..sourceFile = _sourceFile
-          ..begin = _previousOffset + start
-          ..end = _previousOffset + start + name.length;
-    sourceLocationInfo.annotation.add(annotation);
   }
 }
 

protoc_plugin/lib/src/file_generator.dart

@@ -263,14 +263,19 @@ class FileGenerator extends ProtobufContainer {
     final mainWriter = generateMainFile(config);
     final enumWriter = generateEnumFile(config);
 
+    final generateMetadata = options.generateMetadata;
+
     final files = [
-      makeFile('.pb.dart', mainWriter.toString()),
-      makeFile('.pbenum.dart', enumWriter.toString()),
+      makeFile('.pb.dart', mainWriter.emitSource(format: !generateMetadata)),
+      makeFile(
+        '.pbenum.dart',
+        enumWriter.emitSource(format: !generateMetadata),
+      ),
       // TODO(devoncarew): Consider not emitting empty json files.
       makeFile('.pbjson.dart', generateJsonFile(config)),
     ];
 
-    if (options.generateMetadata) {
+    if (generateMetadata) {
       files.addAll([
         makeFile(
           '.pb.dart.meta',
@@ -291,13 +296,17 @@ class FileGenerator extends ProtobufContainer {
         files.add(makeFile('.pbserver.dart', generateServerFile(config)));
       }
     }
+
     return files;
   }
 
   /// Creates an IndentingWriter with metadata generation enabled or disabled.
-  IndentingWriter makeWriter() => IndentingWriter(
-    filename: options.generateMetadata ? descriptor.name : null,
-  );
+  IndentingWriter makeWriter() {
+    return IndentingWriter(
+      fileName: descriptor.name,
+      generateMetadata: options.generateMetadata,
+    );
+  }
 
   /// Returns the contents of the .pb.dart file for this .proto file.
   IndentingWriter generateMainFile([
@@ -569,7 +578,7 @@ class FileGenerator extends ProtobufContainer {
       s.generate(out);
     }
 
-    return out.toString();
+    return out.emitSource(format: true);
   }
 
   /// Returns the contents of the .pbgrpc.dart file for this .proto file.
@@ -606,7 +615,7 @@ class FileGenerator extends ProtobufContainer {
       generator.generate(out);
     }
 
-    return out.toString();
+    return out.emitSource(format: true);
   }
 
   void writeBinaryDescriptor(
@@ -699,7 +708,7 @@ class FileGenerator extends ProtobufContainer {
       out.println('');
     }
 
-    return out.toString();
+    return out.emitSource(format: true);
   }
 
   /// Returns the generator for each .pbjson.dart file the generated

protoc_plugin/lib/src/formatter.dart

@@ -0,0 +1,16 @@
+// 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:dart_style/dart_style.dart';
+import 'package:pub_semver/pub_semver.dart';
+
+// Note: keep this in sync with the SDK constraint in pubspec.yaml.
+final Version formatUsingVersion = Version(3, 6, 0);
+
+final DartFormatter _formatter = DartFormatter(
+  languageVersion: formatUsingVersion,
+);
+
+/// Return the Dart formatted version of the given source.
+String format(String source) => _formatter.format(source);

protoc_plugin/mono_pkg.yaml

@@ -2,7 +2,7 @@
 stages:
   - format_analyze:
     - group:
-      - format
+      - format: --output=none --set-exit-if-changed lib
       - command: ./../tool/setup.sh
       - command: make protos
       - analyze: --fatal-infos

protoc_plugin/pubspec.yaml

@@ -1,23 +1,24 @@
 name: protoc_plugin
-version: 22.4.1-wip
+version: 22.5.0-wip
 description: A protobuf protoc compiler plugin used to generate Dart code.
 repository: https://github.com/google/protobuf.dart/tree/master/protoc_plugin
 
 environment:
+  # Note: keep this in sync with the SDK version in lib/src/formatter.dart.
   sdk: ^3.7.0
 
 resolution: workspace
 
 dependencies:
   collection: ^1.15.0
+  dart_style: ^3.0.0
   fixnum: ^1.0.0
   path: ^1.8.0
   protobuf: ^4.1.0
+  pub_semver: ^2.2.0
 
 dev_dependencies:
-  dart_style: ^3.1.0
   lints: '>=5.0.0 <7.0.0'
-  pub_semver: ^2.2.0
   test: ^1.16.0
 
 executables:

protoc_plugin/test/client_generator_test.dart

@@ -33,6 +33,6 @@ void main() {
 
     final writer = IndentingWriter();
     cag.generate(writer);
-    expectGolden(writer.toString(), 'client.pb.dart');
+    expectGolden(writer.emitSource(format: true), 'client.pb.dart');
   });
 }

protoc_plugin/test/const_generator_test.dart

@@ -9,7 +9,7 @@ import 'package:test/test.dart';
 String toConst(Object? val) {
   final out = IndentingWriter();
   writeJsonConst(out, val);
-  return out.toString();
+  return out.emitSource(format: false);
 }
 
 void main() {