Use surrounding packages to infer language version in the CLI. (#1508)

When formatting file paths using the formatter CLI, look for a
surrounding package (identified by a package config) to infer the
default (i.e. not `// @Dart=`) language version for each formatted file.

Currently, this behavior only happens when the tall-style experiment is
enabled. When that experiment ships, it will be the default behavior.
If the user passes an explicit language version using
"--language-version", then no directory searching happens.

This only affects the CLI behavior. The library API never searches the
file system. Also, when passing input to the formatter CLI over stdin,
it doesn't search the file system.

Author: munificent

bin/format.dart

@@ -138,7 +138,7 @@ void main(List<String> args) async {
   if (argResults.rest.isEmpty) {
     await formatStdin(options, selection, argResults['stdin-name'] as String);
   } else {
-    formatPaths(options, argResults.rest);
+    await formatPaths(options, argResults.rest);
   }
 
   options.summary.show();

lib/src/cli/format_command.dart

@@ -170,7 +170,7 @@ class FormatCommand extends Command<int> {
     if (argResults.rest.isEmpty) {
       await formatStdin(options, selection, stdinName);
     } else {
-      formatPaths(options, argResults.rest);
+      await formatPaths(options, argResults.rest);
       options.summary.show();
     }
 

lib/src/cli/options.dart

@@ -72,7 +72,7 @@ void defineOptions(ArgParser parser,
         help: 'Language version of formatted code.\n'
             'Use "latest" to parse as the latest supported version.\n'
             'Omit to look for a surrounding package config.',
-        // TODO(rnystrom): Show this when package config support is implemented.
+        // TODO(rnystrom): Show this when the tall-style experiment ships.
         hide: true);
   }
 

lib/src/dart_formatter.dart

@@ -244,10 +244,9 @@ class DartFormatter {
         sdkLanguageVersion: version, flags: experiments);
 
     return parseString(
-      content: source,
-      featureSet: featureSet,
-      path: uri,
-      throwIfDiagnostics: false,
-    );
+        content: source,
+        featureSet: featureSet,
+        path: uri,
+        throwIfDiagnostics: false);
   }
 }

lib/src/io.dart

@@ -6,10 +6,13 @@ import 'dart:convert';
 import 'dart:io';
 
 import 'package:path/path.dart' as p;
+import 'package:pub_semver/pub_semver.dart';
 
 import 'cli/formatter_options.dart';
+import 'constants.dart';
 import 'dart_formatter.dart';
 import 'exceptions.dart';
+import 'language_version_cache.dart';
 import 'source_code.dart';
 
 /// Reads and formats input from stdin until closed.
@@ -59,19 +62,29 @@ $stack''');
 }
 
 /// Formats all of the files and directories given by [paths].
-void formatPaths(FormatterOptions options, List<String> paths) {
+Future<void> formatPaths(FormatterOptions options, List<String> paths) async {
+  // If the user didn't specify a language version, then look for surrounding
+  // package configs so we know what language versions to use for the files.
+  LanguageVersionCache? cache;
+  if (options.languageVersion == null) {
+    // TODO(rnystrom): Remove the experiment check when the experiment ships.
+    if (options.experimentFlags.contains(tallStyleExperimentFlag)) {
+      cache = LanguageVersionCache();
+    }
+  }
+
   for (var path in paths) {
     var directory = Directory(path);
     if (directory.existsSync()) {
-      if (!processDirectory(options, directory)) {
+      if (!await _processDirectory(cache, options, directory)) {
         exitCode = 65;
       }
       continue;
     }
 
     var file = File(path);
     if (file.existsSync()) {
-      if (!processFile(options, file)) {
+      if (!await _processFile(cache, options, file)) {
         exitCode = 65;
       }
     } else {
@@ -85,7 +98,8 @@ void formatPaths(FormatterOptions options, List<String> paths) {
 ///
 /// Returns `true` if successful or `false` if an error occurred in any of the
 /// files.
-bool processDirectory(FormatterOptions options, Directory directory) {
+Future<bool> _processDirectory(LanguageVersionCache? cache,
+    FormatterOptions options, Directory directory) async {
   options.showDirectory(directory.path);
 
   var success = true;
@@ -125,7 +139,9 @@ bool processDirectory(FormatterOptions options, Directory directory) {
       continue;
     }
 
-    if (!processFile(options, entry, displayPath: displayPath)) success = false;
+    if (!await _processFile(cache, options, entry, displayPath: displayPath)) {
+      success = false;
+    }
   }
 
   return success;
@@ -134,15 +150,39 @@ bool processDirectory(FormatterOptions options, Directory directory) {
 /// Runs the formatter on [file].
 ///
 /// Returns `true` if successful or `false` if an error occurred.
-bool processFile(FormatterOptions options, File file, {String? displayPath}) {
+Future<bool> _processFile(
+    LanguageVersionCache? cache, FormatterOptions options, File file,
+    {String? displayPath}) async {
   displayPath ??= file.path;
 
+  // Determine what language version to use. If we have a language version
+  // cache, that implies that we should use the surrounding package config to
+  // infer the file's language version. Otherwise, use the user-provided
+  // version.
+  Version? languageVersion;
+  if (cache != null) {
+    try {
+      // Look for a package config. If we don't find one, default to the latest
+      // language version.
+      languageVersion = await cache.find(file);
+    } catch (error) {
+      stderr.writeln('Could not read package configuration for '
+          '$displayPath:\n$error');
+      stderr.writeln('To avoid searching for a package configuration, '
+          'specify a language version using "--language-version".');
+      return false;
+    }
+  } else {
+    languageVersion = options.languageVersion;
+  }
+
   var formatter = DartFormatter(
-      languageVersion: options.languageVersion,
+      languageVersion: languageVersion ?? DartFormatter.latestLanguageVersion,
       indent: options.indent,
       pageWidth: options.pageWidth,
       fixes: options.fixes,
       experimentFlags: options.experimentFlags);
+
   try {
     var source = SourceCode(file.readAsStringSync(), uri: file.path);
     options.beforeFile(file, displayPath);

lib/src/language_version_cache.dart

@@ -0,0 +1,62 @@
+// Copyright (c) 2024, 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 'dart:async';
+import 'dart:io';
+
+import 'package:package_config/package_config.dart';
+import 'package:pub_semver/pub_semver.dart';
+
+import 'profile.dart';
+
+/// Caches the default language version that should be used for files within
+/// directories.
+///
+/// The default language version for a Dart file is found by walking the parent
+/// directories of the file being formatted to look for a
+/// `.dart_tool/package_config.json` file. When found, we cache the result for
+/// the formatted file's parent directory. This way, when formatting multiple
+/// files in the same directory, we don't have to look for and read the package
+/// config multiple times, which is slow.
+///
+/// (When formatting dart_style on a Mac laptop, it would spend as much time
+/// looking for package configs for each file as it did formatting if we don't
+/// cache. Caching makes it ~10x faster to find the language version for each
+/// file.)
+class LanguageVersionCache {
+  /// The previously cached default language version for all files immediately
+  /// within a given directory.
+  ///
+  /// The version may be `null` if we formatted a file in that directory and
+  /// discovered that there is no surrounding package.
+  final Map<String, Version?> _directoryVersions = {};
+
+  /// Looks for a package surrounding [file] and, if found, returns the default
+  /// language version specified by that package.
+  Future<Version?> find(File file) async {
+    Profile.begin('look up package config');
+    try {
+      // Use the cached version (which may be `null`) if present.
+      var directory = file.parent.path;
+      if (_directoryVersions.containsKey(directory)) {
+        return _directoryVersions[directory];
+      }
+
+      // Otherwise, walk the file system and look for it.
+      var config = await findPackageConfig(file.parent);
+      if (config?.packageOf(file.absolute.uri)?.languageVersion
+          case var languageVersion?) {
+        // Store the version as pub_semver's [Version] type because that's
+        // what the analyzer parser uses, which is where the version
+        // ultimately gets used.
+        var version = Version(languageVersion.major, languageVersion.minor, 0);
+        return _directoryVersions[directory] = version;
+      }
+
+      // We weren't able to resolve this file's directory, so don't try again.
+      return _directoryVersions[directory] = null;
+    } finally {
+      Profile.end('look up package config');
+    }
+  }
+}

pubspec.yaml

@@ -12,6 +12,7 @@ dependencies:
   analyzer: '^6.5.0'
   args: ">=1.0.0 <3.0.0"
   collection: "^1.17.0"
+  package_config: ^2.1.0
   path: ^1.0.0
   pub_semver: ">=1.4.4 <3.0.0"
   source_span: ^1.4.0

test/command_test.dart

@@ -576,5 +576,116 @@ main() {
       await process.stderr.cancel();
       await process.shouldExit(65);
     });
+
+    group('package config', () {
+      // TODO(rnystrom): Remove this test when the experiment ships.
+      test('no package search if experiment is off', () async {
+        // Put the file in a directory with a malformed package config. If we
+        // search for it, we should get an error.
+        await d.dir('foo', [
+          d.dir('.dart_tool', [
+            d.file('package_config.json', 'this no good json is bad json'),
+          ]),
+          d.file('main.dart', 'main(){    }'),
+        ]).create();
+
+        var process = await runCommandOnDir();
+        await process.shouldExit(0);
+
+        // Should format the file without any error reading the package config.
+        await d.dir('foo', [d.file('main.dart', 'main() {}\n')]).validate();
+      });
+
+      test('no package search if language version is specified', () async {
+        // Put the file in a directory with a malformed package config. If we
+        // search for it, we should get an error.
+        await d.dir('foo', [
+          d.dir('.dart_tool', [
+            d.file('package_config.json', 'this no good json is bad json'),
+          ]),
+          d.file('main.dart', 'main(){    }'),
+        ]).create();
+
+        var process = await runCommandOnDir(
+            ['--language-version=latest', '--enable-experiment=tall-style']);
+        await process.shouldExit(0);
+
+        // Should format the file without any error reading the package config.
+        await d.dir('foo', [d.file('main.dart', 'main() {}\n')]).validate();
+      });
+
+      test('default to language version of surrounding package', () async {
+        // The package config sets the language version to 3.1, but the switch
+        // case uses a syntax which is valid in earlier versions of Dart but an
+        // error in 3.0 and later. Verify that the error is reported (instead of
+        // the formatter falling back to try to parse the file at the older
+        // language version).
+        await d.dir('foo', [
+          packageConfig('foo', 3, 1),
+          d.file('main.dart', 'main() { switch (o) { case 1 + 2: break; } }'),
+        ]).create();
+
+        var path = p.join(d.sandbox, 'foo', 'main.dart');
+        // TODO(rnystrom): Remove experiment flag when it ships.
+        var process =
+            await runCommand([path, '--enable-experiment=tall-style']);
+
+        expect(await process.stderr.next,
+            'Could not format because the source could not be parsed:');
+        expect(await process.stderr.next, '');
+        expect(await process.stderr.next, contains(p.join('foo', 'main.dart')));
+        await process.shouldExit(65);
+      });
+
+      test('language version comment overrides package default', () async {
+        // The package config sets the language version to 3.1, but the switch
+        // case uses a syntax which is valid in earlier versions of Dart but an
+        // error in 3.0 and later. Verify that no error is reported since this
+        // file opts to the older version.
+        await d.dir('foo', [
+          packageConfig('foo', 3, 1),
+          d.file('main.dart', '''
+          // @dart=2.19
+          main() { switch (obj) { case 1 + 2: // Error in 3.1.
+            } }
+          '''),
+        ]).create();
+
+        var process = await runCommandOnDir();
+        await process.shouldExit(0);
+
+        // Formats the file.
+        await d.dir('foo', [
+          d.file('main.dart', '''
+// @dart=2.19
+main() {
+  switch (obj) {
+    case 1 + 2: // Error in 3.1.
+  }
+}
+''')
+        ]).validate();
+      });
+
+      test('malformed', () async {
+        await d.dir('foo', [
+          d.dir('.dart_tool', [
+            d.file('package_config.json', 'this no good json is bad json'),
+          ]),
+          d.file('main.dart', 'main() {}'),
+        ]).create();
+
+        var path = p.join(d.sandbox, 'foo', 'main.dart');
+        // TODO(rnystrom): Remove experiment flag when it ships.
+        var process =
+            await runCommand([path, '--enable-experiment=tall-style']);
+
+        expect(
+            await process.stderr.next,
+            allOf(startsWith('Could not read package configuration for'),
+                contains(p.join('foo', 'main.dart'))));
+        await process.shouldExit(65);
+      });
+    });
   });
 }