pkgs/extension_discovery/lib/extension_discovery.dart - tools.git - Git at Google

 // Copyright (c) 2023, 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.

 /// Find extensions with [findExtensions].
 library;

 import 'dart:collection' show UnmodifiableListView;
 import 'dart:io' show File, IOException;
 import 'dart:isolate' show Isolate;

 import 'src/io.dart';
 import 'src/package_config.dart';
 import 'src/registry.dart';
 import 'src/yaml_config_format.dart';

 export 'src/package_config.dart' show PackageConfigException, findPackageConfig;

 /// Information about an extension for target package.
 final class Extension {
   /// Name of the package providing an extension.
   final String package;

   /// Absolute path to the package root.
   ///
   /// This folder usually contains a `lib/` folder and a `pubspec.yaml`
   /// (assuming dependencies are fetched using the pub package manager).
   ///
   /// **Examples:** If `foo` is installed in pub-cache this would be:
   ///  * `/home/my_user/.pub-cache/hosted/pub.dev/foo-1.0.0/`
   ///
   /// See `rootUri` in the [specification for `package_config.json`][1],
   /// for details.
   ///
   /// [1]: https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md
   final Uri rootUri;

   /// Path to the library import path relative to [rootUri].
   ///
   /// In Dart code the `package:<package>/<path>` will be resolved as
   /// `<rootUri>/<packageUri>/<path>`.
   ///
   /// If dependencies are installed using `dart pub`, then this is
   /// **always** `lib/`.
   ///
   /// See `packageUri` in the [specification for `package_config.json`][1],
   /// for details.
   ///
   /// [1]: https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md
   final Uri packageUri;

   /// Contents of `extension/<targetPackage>/config.yaml` parsed as YAML and
   /// converted to JSON compatible types.
   ///
   /// If parsing YAML from this file failed, then no [Extension] entry
   /// will exist.
   ///
   /// This field is always a structure consisting of the following types:
   ///  * `null`,
   ///  * [bool] (`true` or `false`),
   ///  * [String],
   ///  * [num] ([int] or [double]),
   ///  * `List<Object?>`, and,
   ///  * `Map<String, Object?>`.
   final Map<String, Object?> config;

   Extension._({
     required this.package,
     required this.rootUri,
     required this.packageUri,
     required this.config,
   });
 }

 /// Find extensions for [targetPackage] provided by packages in
 /// `.dart_tool/package_config.json`.
 ///
 /// ## Locating `.dart_tool/package_config.json`
 ///
 /// This method requires the location of the [packageConfig], unless the current
 /// isolate has been setup for package resolution.
 /// Notably, Dart programs compiled for AOT cannot find their own
 /// `package_config.json`.
 ///
 /// If operating on a project that isn't the current project, for example, if
 /// you are developing a tool that users are globally activating and then
 /// running against their own projects, and you wish to detect extensions within
 /// their projects, then you must specify the path the
 /// `.dart_tool/package_config.json` for the users project as [packageConfig].
 ///
 /// The [packageConfig] parameter must reference a file, absolute or
 /// relative-path, may use the `file://` scheme. This method throws, if
 /// [packageConfig] is not a valid [Uri] for a file-path.
 ///
 /// ## Detection of extensions
 ///
 /// An extension for [targetPackage] is detected in `package:foo` if `foo`
 /// contains `extension/<targetPackage>/config.yaml`, and the contents of this
 /// file is valid YAML, that can be represented as JSON.
 ///
 /// ### Caching results
 ///
 /// When [useCache] is `true` then the detected extensions will be cached
 /// in `.dart_tool/extension_discovery/<targetPackage>.json`.
 /// This function will compare modification timestamps of
 /// `.dart_tool/package_config.json` with the cache file, before reusing cached
 /// results.
 /// This function will also treat relative path-dependencies as mutable
 /// packages, and check such packages for extensions every time [findExtensions]
 /// is called. Notably, it'll compare the modification time of the
 /// `extension/<targetPackage>/config.yaml` file, to ensure that it's older than
 /// the extension cache file. Otherwise, it'll reload the extension
 /// configuration.
 ///
 /// ## Exceptions
 ///
 /// This method will throw [PackageConfigException], if the
 /// `.dart_tool/package_config.json` file specified in [packageConfig] could not
 /// be loaded or is invalid. This usually happens if dependencies are not
 /// resolved, and users can probably address it by running `dart pub get`.
 ///
 /// But, **do consider catch** [PackageConfigException] and handling the failure
 /// to load extensions appropriately.
 ///
 /// This method will throw an [Error] if [packageConfig] is not specified, and
 /// the current isolate isn't configured for package resolution.
 Future<List<Extension>> findExtensions(
   String targetPackage, {
   bool useCache = true,
   Uri? packageConfig,
 }) async {
   packageConfig ??= await Isolate.packageConfig;
   if (packageConfig == null) {
     throw UnsupportedError(
       'packageConfigUri must be provided, if not running in JIT mode',
     );
   }
   if ((packageConfig.hasScheme && !packageConfig.isScheme('file')) ||
       packageConfig.hasEmptyPath ||
       packageConfig.hasFragment ||
       packageConfig.hasPort ||
       packageConfig.hasQuery) {
     throw ArgumentError.value(
       packageConfig,
       'packageConfig',
       'must be a file:// URI',
     );
   }
   // Always normalize to an absolute URI
   final packageConfigUri = File.fromUri(packageConfig).absolute.uri;

   return await _findExtensions(
     targetPackage: targetPackage,
     useCache: useCache,
     packageConfigUri: packageConfigUri,
   );
 }

 /// Find extensions with normalized arguments.
 Future<List<Extension>> _findExtensions({
   required String targetPackage,
   required bool useCache,
   required Uri packageConfigUri,
 }) async {
   final packageConfigFile = File.fromUri(packageConfigUri);
   final registryFile = File.fromUri(packageConfigFile.parent.uri.resolve(
     'extension_discovery/$targetPackage.json',
   ));

   Registry? registry;
   final registryStat = registryFile.statSync();
   if (registryStat.isFileOrLink && useCache) {
     final packageConfigStat = packageConfigFile.statSync();
     if (!packageConfigStat.isFileOrLink) {
       throw packageConfigNotFound(packageConfigUri);
     }
     if (packageConfigStat.isPossiblyModifiedAfter(registryStat.modified)) {
       await registryFile.tryDelete();
     } else {
       registry = await loadRegistry(registryFile);
     }
   }

   final configFileName = 'extension/$targetPackage/config.yaml';
   var registryUpdated = false;
   if (registry != null) {
     // Update mutable entries in registry
     for (var i = 0; i < registry.length; i++) {
       final p = registry[i];
       if (p.rootUri.hasAbsolutePath) continue;

       final rootUri = packageConfigUri.resolveUri(p.rootUri);
       final configFile = File.fromUri(rootUri.resolve(configFileName));
       final configStat = configFile.statSync();
       if (configStat.isFileOrLink) {
         if (configStat.isPossiblyModifiedAfter(registryStat.modified)) {
           try {
             registryUpdated = true;
             registry[i] = (
               package: p.package,
               rootUri: p.rootUri,
               packageUri: p.packageUri,
               config: parseYamlFromConfigFile(await configFile.readAsString()),
             );
             continue;
           } on FormatException {
             // pass
           } on IOException {
             // pass
           }
           registryUpdated = true;
           registry[i] = (
             package: p.package,
             rootUri: p.rootUri,
             packageUri: p.packageUri,
             config: null,
           );
         }
       } else {
         // If there is no file present, but registry says there is then we need
         // to update the registry.
         if (p.config != null) {
           registryUpdated = true;
           registry[i] = (
             package: p.package,
             rootUri: p.rootUri,
             packageUri: p.packageUri,
             config: null,
           );
         }
       }
     }
   } else {
     // Load packages from package_config.json
     final packages = await loadPackageConfig(packageConfigFile);
     registryUpdated = true;
     registry = (await Future.wait(packages.map((p) async {
       try {
         final rootUri = packageConfigUri.resolveUri(p.rootUri);
         final configFile = File.fromUri(rootUri.resolve(configFileName));
         final configStat = configFile.statSync();
         if (configStat.isFileOrLink) {
           return (
             package: p.name,
             rootUri: p.rootUri,
             packageUri: p.packageUri,
             config: parseYamlFromConfigFile(await configFile.readAsString()),
           );
         }
       } on FormatException {
         // pass
       } on IOException {
         // pass
       }
       if (!p.rootUri.hasAbsolutePath) {
         return (
           package: p.name,
           rootUri: p.rootUri,
           packageUri: p.packageUri,
           config: null,
         );
       }
       return null;
     })))
         .whereType<RegistryEntry>()
         .toList(growable: false);
   }

   // Save registry
   if (registryUpdated && useCache) {
     await saveRegistry(registryFile, registry);
   }

   return UnmodifiableListView(
     registry
         .where((e) => e.config != null)
         .map((e) => Extension._(
               package: e.package,
               rootUri: packageConfigUri.resolveUri(e.rootUri),
               packageUri: e.packageUri,
               config: e.config!,
             ))
         .toList(growable: false),
   );
 }
	// Copyright (c) 2023, 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.

	/// Find extensions with [findExtensions].
	library;

	import 'dart:collection' show UnmodifiableListView;
	import 'dart:io' show File, IOException;
	import 'dart:isolate' show Isolate;

	import 'src/io.dart';
	import 'src/package_config.dart';
	import 'src/registry.dart';
	import 'src/yaml_config_format.dart';

	export 'src/package_config.dart' show PackageConfigException, findPackageConfig;

	/// Information about an extension for target package.
	final class Extension {
	/// Name of the package providing an extension.
	final String package;

	/// Absolute path to the package root.
	///
	/// This folder usually contains a `lib/` folder and a `pubspec.yaml`
	/// (assuming dependencies are fetched using the pub package manager).
	///
	/// Examples: If `foo` is installed in pub-cache this would be:
	/// * `/home/my_user/.pub-cache/hosted/pub.dev/foo-1.0.0/`
	///
	/// See `rootUri` in the [specification for `package_config.json`][1],
	/// for details.
	///
	/// [1]: https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md
	final Uri rootUri;

	/// Path to the library import path relative to [rootUri].
	///
	/// In Dart code the `package:<package>/<path>` will be resolved as
	/// `<rootUri>/<packageUri>/<path>`.
	///
	/// If dependencies are installed using `dart pub`, then this is
	/// always `lib/`.
	///
	/// See `packageUri` in the [specification for `package_config.json`][1],
	/// for details.
	///
	/// [1]: https://github.com/dart-lang/language/blob/main/accepted/2.8/language-versioning/package-config-file-v2.md
	final Uri packageUri;

	/// Contents of `extension/<targetPackage>/config.yaml` parsed as YAML and
	/// converted to JSON compatible types.
	///
	/// If parsing YAML from this file failed, then no [Extension] entry
	/// will exist.
	///
	/// This field is always a structure consisting of the following types:
	/// * `null`,
	/// * [bool] (`true` or `false`),
	/// * [String],
	/// * [num] ([int] or [double]),
	/// * `List<Object?>`, and,
	/// * `Map<String, Object?>`.
	final Map<String, Object?> config;

	Extension._({
	required this.package,
	required this.rootUri,
	required this.packageUri,
	required this.config,
	});
	}

	/// Find extensions for [targetPackage] provided by packages in
	/// `.dart_tool/package_config.json`.
	///
	/// ## Locating `.dart_tool/package_config.json`
	///
	/// This method requires the location of the [packageConfig], unless the current
	/// isolate has been setup for package resolution.
	/// Notably, Dart programs compiled for AOT cannot find their own
	/// `package_config.json`.
	///
	/// If operating on a project that isn't the current project, for example, if
	/// you are developing a tool that users are globally activating and then
	/// running against their own projects, and you wish to detect extensions within
	/// their projects, then you must specify the path the
	/// `.dart_tool/package_config.json` for the users project as [packageConfig].
	///
	/// The [packageConfig] parameter must reference a file, absolute or
	/// relative-path, may use the `file://` scheme. This method throws, if
	/// [packageConfig] is not a valid [Uri] for a file-path.
	///
	/// ## Detection of extensions
	///
	/// An extension for [targetPackage] is detected in `package:foo` if `foo`
	/// contains `extension/<targetPackage>/config.yaml`, and the contents of this
	/// file is valid YAML, that can be represented as JSON.
	///
	/// ### Caching results
	///
	/// When [useCache] is `true` then the detected extensions will be cached
	/// in `.dart_tool/extension_discovery/<targetPackage>.json`.
	/// This function will compare modification timestamps of
	/// `.dart_tool/package_config.json` with the cache file, before reusing cached
	/// results.
	/// This function will also treat relative path-dependencies as mutable
	/// packages, and check such packages for extensions every time [findExtensions]
	/// is called. Notably, it'll compare the modification time of the
	/// `extension/<targetPackage>/config.yaml` file, to ensure that it's older than
	/// the extension cache file. Otherwise, it'll reload the extension
	/// configuration.
	///
	/// ## Exceptions
	///
	/// This method will throw [PackageConfigException], if the
	/// `.dart_tool/package_config.json` file specified in [packageConfig] could not
	/// be loaded or is invalid. This usually happens if dependencies are not
	/// resolved, and users can probably address it by running `dart pub get`.
	///
	/// But, do consider catch [PackageConfigException] and handling the failure
	/// to load extensions appropriately.
	///
	/// This method will throw an [Error] if [packageConfig] is not specified, and
	/// the current isolate isn't configured for package resolution.
	Future<List<Extension>> findExtensions(
	String targetPackage, {
	bool useCache = true,
	Uri? packageConfig,
	}) async {
	packageConfig ??= await Isolate.packageConfig;
	if (packageConfig == null) {
	throw UnsupportedError(
	'packageConfigUri must be provided, if not running in JIT mode',
	);
	}
	if ((packageConfig.hasScheme && !packageConfig.isScheme('file')) \|\|
	packageConfig.hasEmptyPath \|\|
	packageConfig.hasFragment \|\|
	packageConfig.hasPort \|\|
	packageConfig.hasQuery) {
	throw ArgumentError.value(
	packageConfig,
	'packageConfig',
	'must be a file:// URI',
	);
	}
	// Always normalize to an absolute URI
	final packageConfigUri = File.fromUri(packageConfig).absolute.uri;

	return await _findExtensions(
	targetPackage: targetPackage,
	useCache: useCache,
	packageConfigUri: packageConfigUri,
	);
	}

	/// Find extensions with normalized arguments.
	Future<List<Extension>> _findExtensions({
	required String targetPackage,
	required bool useCache,
	required Uri packageConfigUri,
	}) async {
	final packageConfigFile = File.fromUri(packageConfigUri);
	final registryFile = File.fromUri(packageConfigFile.parent.uri.resolve(
	'extension_discovery/$targetPackage.json',
	));

	Registry? registry;
	final registryStat = registryFile.statSync();
	if (registryStat.isFileOrLink && useCache) {
	final packageConfigStat = packageConfigFile.statSync();
	if (!packageConfigStat.isFileOrLink) {
	throw packageConfigNotFound(packageConfigUri);
	}
	if (packageConfigStat.isPossiblyModifiedAfter(registryStat.modified)) {
	await registryFile.tryDelete();
	} else {
	registry = await loadRegistry(registryFile);
	}
	}

	final configFileName = 'extension/$targetPackage/config.yaml';
	var registryUpdated = false;
	if (registry != null) {
	// Update mutable entries in registry
	for (var i = 0; i < registry.length; i++) {
	final p = registry[i];
	if (p.rootUri.hasAbsolutePath) continue;

	final rootUri = packageConfigUri.resolveUri(p.rootUri);
	final configFile = File.fromUri(rootUri.resolve(configFileName));
	final configStat = configFile.statSync();
	if (configStat.isFileOrLink) {
	if (configStat.isPossiblyModifiedAfter(registryStat.modified)) {
	try {
	registryUpdated = true;
	registry[i] = (
	package: p.package,
	rootUri: p.rootUri,
	packageUri: p.packageUri,
	config: parseYamlFromConfigFile(await configFile.readAsString()),
	);
	continue;
	} on FormatException {
	// pass
	} on IOException {
	// pass
	}
	registryUpdated = true;
	registry[i] = (
	package: p.package,
	rootUri: p.rootUri,
	packageUri: p.packageUri,
	config: null,
	);
	}
	} else {
	// If there is no file present, but registry says there is then we need
	// to update the registry.
	if (p.config != null) {
	registryUpdated = true;
	registry[i] = (
	package: p.package,
	rootUri: p.rootUri,
	packageUri: p.packageUri,
	config: null,
	);
	}
	}
	}
	} else {
	// Load packages from package_config.json
	final packages = await loadPackageConfig(packageConfigFile);
	registryUpdated = true;
	registry = (await Future.wait(packages.map((p) async {
	try {
	final rootUri = packageConfigUri.resolveUri(p.rootUri);
	final configFile = File.fromUri(rootUri.resolve(configFileName));
	final configStat = configFile.statSync();
	if (configStat.isFileOrLink) {
	return (
	package: p.name,
	rootUri: p.rootUri,
	packageUri: p.packageUri,
	config: parseYamlFromConfigFile(await configFile.readAsString()),
	);
	}
	} on FormatException {
	// pass
	} on IOException {
	// pass
	}
	if (!p.rootUri.hasAbsolutePath) {
	return (
	package: p.name,
	rootUri: p.rootUri,
	packageUri: p.packageUri,
	config: null,
	);
	}
	return null;
	})))
	.whereType<RegistryEntry>()
	.toList(growable: false);
	}

	// Save registry
	if (registryUpdated && useCache) {
	await saveRegistry(registryFile, registry);
	}

	return UnmodifiableListView(
	registry
	.where((e) => e.config != null)
	.map((e) => Extension._(
	package: e.package,
	rootUri: packageConfigUri.resolveUri(e.rootUri),
	packageUri: e.packageUri,
	config: e.config!,
	))
	.toList(growable: false),
	);
	}