Remove uspport for .packages files.

Simplify (braking) API which no longer needs to support two files.

Since this is breaking anyway, add `final` to classes,
and make comparison operators on `LanguageVersion` instance methods.

Add tool to query package configuration for a file or directory:
`bin/package_config_of.dart`.

Author: lrhn

pkgs/package_config/CHANGELOG.md

@@ -1,10 +1,24 @@
-## 2.2.0-wip
+## 3.0.0
 
-- Add relational operators to `LanguageVersion` with extension methods
-  exported under `LanguageVersionRelationalOperators`.
+- Removes support for the `.packages` file.
+  The Dart SDK no longer supports that file, and no new `.packages` files
+  will be generated.
 
-- Include correct parameter names in errors when validating
-  the `major` and `minor` versions in the `LanguageVersion.new` constructor.
+- **Breaking change**
+  Simplifies API that no longer needs to support two separate files.
+  - Renamed `readAnyConfigFile` to `readConfigFile`, and removed
+    the `preferNewest` parameter.
+  - Same for `readAnyConfigFileUri` which becomes `readConfigFileUri`.
+
+  Also makes `PackageConfig`, `Package` and `LanguageVersion` final classes.
+
+- Adds `PackageConfig.minVersion` to complement `.maxVersion`.
+  Currently both are `2`.
+
+- Adds relational operators to `LanguageVersion`.
+
+- Includes correct parameter names in errors when validating
+  the `major` and `minor` versions in the `LanguageVersion()` constructor.
 
 ## 2.1.1
 

pkgs/package_config/README.md

@@ -21,6 +21,5 @@ The primary libraries of this package are
     Just the `PackageConfig` class and other types needed to use
     package configurations. This library does not depend on `dart:io`.
 
-The package includes deprecated backwards compatible functionality to
-work with the `.packages` file. This functionality will not be maintained,
-and will be removed in a future version of this package.
+The package no longer contains backwards compatible functionality to
+work with `.packages` files.

pkgs/package_config/lib/package_config.dart

@@ -21,47 +21,27 @@ export 'package_config_types.dart';
 
 /// Reads a specific package configuration file.
 ///
-/// The file must exist and be readable.
-/// It must be either a valid `package_config.json` file
-/// or a valid `.packages` file.
-/// It is considered a `package_config.json` file if its first character
-/// is a `{`.
-///
-/// If the file is a `.packages` file (the file name is `.packages`)
-/// and [preferNewest] is true, the default, also checks if there is
-/// a `.dart_tool/package_config.json` file next
-/// to the original file, and if so, loads that instead.
-/// If [preferNewest] is set to false, a directly specified `.packages` file
-/// is loaded even if there is an available `package_config.json` file.
-/// The caller can determine this from the [PackageConfig.version]
-/// being 1 and look for a `package_config.json` file themselves.
+/// The file must exist, be readable and be a valid `package_config.json` file.
 ///
 /// If [onError] is provided, the configuration file parsing will report errors
 /// by calling that function, and then try to recover.
 /// The returned package configuration is a *best effort* attempt to create
 /// a valid configuration from the invalid configuration file.
 /// If no [onError] is provided, errors are thrown immediately.
 Future<PackageConfig> loadPackageConfig(File file,
+        {void Function(Object error)? onError}) =>
+    readConfigFile(file, onError ?? throwError);
+
+/// @nodoc
+@Deprecated('use loadPackageConfig instead')
+Future<PackageConfig> loadAnyPackageConfig(File file,
         {bool preferNewest = true, void Function(Object error)? onError}) =>
-    readAnyConfigFile(file, preferNewest, onError ?? throwError);
+    loadPackageConfig(file, onError: onError);
 
 /// Reads a specific package configuration URI.
 ///
-/// The file of the URI must exist and be readable.
-/// It must be either a valid `package_config.json` file
-/// or a valid `.packages` file.
-/// It is considered a `package_config.json` file if its first
-/// non-whitespace character is a `{`.
-///
-/// If [preferNewest] is true, the default, and the file is a `.packages` file,
-/// as determined by its file name being `.packages`,
-/// first checks if there is a `.dart_tool/package_config.json` file
-/// next to the original file, and if so, loads that instead.
-/// The [file] *must not* be a `package:` URI.
-/// If [preferNewest] is set to false, a directly specified `.packages` file
-/// is loaded even if there is an available `package_config.json` file.
-/// The caller can determine this from the [PackageConfig.version]
-/// being 1 and look for a `package_config.json` file themselves.
+/// The file of the URI must exist, be readable,
+/// and be  a valid `package_config.json` file.
 ///
 /// If [loader] is provided, URIs are loaded using that function.
 /// The future returned by the loader must complete with a [Uint8List]
@@ -88,15 +68,19 @@ Future<PackageConfig> loadPackageConfig(File file,
 /// If no [onError] is provided, errors are thrown immediately.
 Future<PackageConfig> loadPackageConfigUri(Uri file,
         {Future<Uint8List?> Function(Uri uri)? loader,
-        bool preferNewest = true,
         void Function(Object error)? onError}) =>
-    readAnyConfigFileUri(file, loader, onError ?? throwError, preferNewest);
+    readConfigFileUri(file, loader, onError ?? throwError);
+
+/// @nodoc
+@Deprecated('use loadPackageConfigUri instead')
+Future<PackageConfig> loadAnyPackageConfigUri(Uri uri,
+        {bool preferNewest = true, void Function(Object error)? onError}) =>
+    loadPackageConfigUri(uri, onError: onError);
 
 /// Finds a package configuration relative to [directory].
 ///
-/// If [directory] contains a package configuration,
-/// either a `.dart_tool/package_config.json` file or,
-/// if not, a `.packages`, then that file is loaded.
+/// If [directory] contains a `.dart_tool/package_config.json` file,
+/// then that file is loaded.
 ///
 /// If no file is found in the current directory,
 /// then the parent directories are checked recursively,
@@ -129,9 +113,8 @@ Future<PackageConfig?> findPackageConfig(Directory directory,
 
 /// Finds a package configuration relative to [location].
 ///
-/// If [location] contains a package configuration,
-/// either a `.dart_tool/package_config.json` file or,
-/// if not, a `.packages`, then that file is loaded.
+/// If [location] contains a `.dart_tool/package_config.json`
+/// package configuration file or, then that file is loaded.
 /// The [location] URI *must not* be a `package:` URI.
 /// It should be a hierarchical URI which is supported
 /// by [loader].
@@ -189,9 +172,6 @@ Future<PackageConfig?> findPackageConfigUri(Uri location,
 /// If the `.dart_tool/` directory does not exist, it is created.
 /// If it cannot be created, this operation fails.
 ///
-/// Also writes a `.packages` file in [directory].
-/// This will stop happening eventually as the `.packages` file becomes
-/// discontinued.
 /// A comment is generated if `[PackageConfig.extraData]` contains a
 /// `"generator"` entry.
 Future<void> savePackageConfig(

pkgs/package_config/lib/package_config_types.dart

@@ -17,6 +17,5 @@ export 'src/package_config.dart'
     show
         InvalidLanguageVersion,
         LanguageVersion,
-        LanguageVersionRelationalOperators,
         Package,
         PackageConfig;

pkgs/package_config/lib/src/discovery.dart

@@ -6,14 +6,12 @@ import 'dart:io';
 import 'dart:typed_data';
 
 import 'errors.dart';
-import 'package_config_impl.dart';
+import 'package_config.dart';
 import 'package_config_io.dart';
 import 'package_config_json.dart';
-import 'packages_file.dart' as packages_file;
 import 'util_io.dart' show defaultLoader, pathJoin;
 
 final Uri packageConfigJsonPath = Uri(path: '.dart_tool/package_config.json');
-final Uri dotPackagesPath = Uri(path: '.packages');
 final Uri currentPath = Uri(path: '.');
 final Uri parentPath = Uri(path: '..');
 
@@ -24,16 +22,13 @@ final Uri parentPath = Uri(path: '..');
 /// and stopping when something is found.
 ///
 /// * Check if a `.dart_tool/package_config.json` file exists in the directory.
-/// * Check if a `.packages` file exists in the directory
-///   (if `minVersion <= 1`).
-/// * Repeat these checks for the parent directories until reaching the
+/// * Repeat this check for the parent directories until reaching the
 ///   root directory if [recursive] is true.
 ///
-/// If any of these tests succeed, a `PackageConfig` class is returned.
+/// If any such a test succeeds, a `PackageConfig` class is returned.
 /// Returns `null` if no configuration was found. If a configuration
 /// is needed, then the caller can supply [PackageConfig.empty].
 ///
-/// If [minVersion] is greater than 1, `.packages` files are ignored.
 /// If [minVersion] is greater than the version read from the
 /// `package_config.json` file, it too is ignored.
 Future<PackageConfig?> findPackageConfig(Directory baseDirectory,
@@ -44,7 +39,6 @@ Future<PackageConfig?> findPackageConfig(Directory baseDirectory,
     return null;
   }
   do {
-    // Check for $cwd/.packages
     var packageConfig =
         await findPackageConfigInDirectory(directory, minVersion, onError);
     if (packageConfig != null) return packageConfig;
@@ -87,13 +81,6 @@ Future<PackageConfig?> findPackageConfigUri(
       var config = parsePackageConfigBytes(bytes, file, onError);
       if (config.version >= minVersion) return config;
     }
-    if (minVersion <= 1) {
-      file = location.resolveUri(dotPackagesPath);
-      bytes = await loader(file);
-      if (bytes != null) {
-        return packages_file.parse(bytes, file, onError);
-      }
-    }
     if (!recursive) break;
     var parent = location.resolveUri(parentPath);
     if (parent == location) break;
@@ -102,7 +89,7 @@ Future<PackageConfig?> findPackageConfigUri(
   return null;
 }
 
-/// Finds a `.packages` or `.dart_tool/package_config.json` file in [directory].
+/// Finds a `.dart_tool/package_config.json` file in [directory].
 ///
 /// Loads the file, if it is there, and returns the resulting [PackageConfig].
 /// Returns `null` if the file isn't there.
@@ -113,7 +100,6 @@ Future<PackageConfig?> findPackageConfigUri(
 /// a best-effort attempt is made to return a package configuration.
 /// This may be the empty package configuration.
 ///
-/// If [minVersion] is greater than 1, `.packages` files are ignored.
 /// If [minVersion] is greater than the version read from the
 /// `package_config.json` file, it too is ignored.
 Future<PackageConfig?> findPackageConfigInDirectory(Directory directory,
@@ -124,12 +110,6 @@ Future<PackageConfig?> findPackageConfigInDirectory(Directory directory,
     if (config.version < minVersion) return null;
     return config;
   }
-  if (minVersion <= 1) {
-    packageConfigFile = await checkForDotPackagesFile(directory);
-    if (packageConfigFile != null) {
-      return await readDotPackagesFile(packageConfigFile, onError);
-    }
-  }
   return null;
 }
 
@@ -140,9 +120,3 @@ Future<File?> checkForPackageConfigJsonFile(Directory directory) async {
   if (await file.exists()) return file;
   return null;
 }
-
-Future<File?> checkForDotPackagesFile(Directory directory) async {
-  var file = File(pathJoin(directory.path, '.packages'));
-  if (await file.exists()) return file;
-  return null;
-}