Add a way to opt a file out of Dart formatting

Author: Hixie

script/tool/CHANGELOG.md

@@ -12,6 +12,8 @@
   `--packages` flag used by most other packages.
 - **Breaking change** Passing both `--run-on-changed-packages` and `--packages`
   is now an error; previously it the former would be ignored.
+- Formatting now skips files that contain a line that exactly
+  matches the string `// This file is hand-formatted.`.
 
 ## 0.5.0
 

script/tool/lib/src/format_command.dart

@@ -206,7 +206,27 @@ class FormatCommand extends PluginCommand {
 
     final String fromPath = relativeTo.path;
 
+    // Dart files are allowed to have a pragma to disable auto-formatting. This
+    // was added because Hixie hurts when dealing with what dartfmt does to
+    // artisanally-formatted Dart, while Stuart gets really frustrated when
+    // dealing with PRs from newer contributors who don't know how to make Dart
+    // readable. After much discussion, it was decided that files in the plugins
+    // and packages repos that really benefit from hand-formatting (e.g. files
+    // with large blobs of hex literals) could be opted-out of the requirement
+    // that they be autoformatted, so long as the code's owner was willing to
+    // bear the cost of this during code reviews.
+    // In the event that code ownership moves to someone who does not hold the
+    // same views as the original owner, the pragma can be removed and the file
+    // auto-formatted.
+    const String handFormattedExtension = '.dart';
+    const String handFormattedPragma = '// This file is hand-formatted.';
+
     return files
+        .where((File file) {
+          // See comment above near [handFormattedPragma].
+          return path.extension(file.path) != handFormattedExtension ||
+              !file.readAsLinesSync().contains(handFormattedPragma);
+        })
         .map((File file) => path.relative(file.path, from: fromPath))
         .where((String path) =>
             // Ignore files in build/ directories (e.g., headers of frameworks)

script/tool/test/format_command_test.dart

@@ -8,6 +8,7 @@ import 'package:args/command_runner.dart';
 import 'package:file/file.dart';
 import 'package:file/memory.dart';
 import 'package:flutter_plugin_tools/src/common/core.dart';
+import 'package:flutter_plugin_tools/src/common/file_utils.dart';
 import 'package:flutter_plugin_tools/src/format_command.dart';
 import 'package:path/path.dart' as p;
 import 'package:test/test.dart';
@@ -85,6 +86,7 @@ void main() {
       'lib/src/b.dart',
       'lib/src/c.dart',
     ];
+    const String fileWithOptOut = 'lib/src/d.dart';
     final Directory pluginDir = createFakePlugin(
       'a_plugin',
       packagesDir,
@@ -106,6 +108,42 @@ void main() {
         ]));
   });
 
+  test('does not format .dart files with pragma', () async {
+    const List<String> formattedFiles = <String>[
+      'lib/a.dart',
+      'lib/src/b.dart',
+      'lib/src/c.dart',
+    ];
+    const String unformattedFile = 'lib/src/d.dart';
+    final Directory pluginDir = createFakePlugin(
+      'a_plugin',
+      packagesDir,
+      extraFiles: <String>[
+        ...formattedFiles,
+        unformattedFile,
+      ],
+    );
+
+    final p.Context posixContext = p.posix;
+    childFileWithSubcomponents(pluginDir, posixContext.split(unformattedFile))
+        .writeAsStringSync(
+            '// copyright bla bla\n// This file is hand-formatted.\ncode...');
+
+    await runCapturingPrint(runner, <String>['format']);
+
+    expect(
+        processRunner.recordedCalls,
+        orderedEquals(<ProcessCall>[
+          ProcessCall(
+              getFlutterCommand(mockPlatform),
+              <String>[
+                'format',
+                ..._getPackagesDirRelativePaths(pluginDir, formattedFiles)
+              ],
+              packagesDir.path),
+        ]));
+  });
+
   test('fails if flutter format fails', () async {
     const List<String> files = <String>[
       'lib/a.dart',