analyzer_testing: improve error message when trying to use built-in mocks

Work towards #61597

The analyzer_testing package's mock packages are "data" or "resource"
files which are notoriously hard to find on disk. No dart tooling I
know of can give me "the root directory of a package which is
referenced in a Dart program via "package:". Konstantin notes that
a program may be compiled ahead of time, and so the running VM itself
does not know where source files originally came from.

When users of the analyzer_testing package try to use
`addFlutterPackageDep` in a test, which attempts to locate the Dart
SDK's `pkg/` root directory, they get a StateError. This CL adds more
information and context to that error.

Change-Id: I3ae55cd580c8fa16ca86d66e6f7b655b8f9bcc42
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/452532
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analyzer_testing/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.1.4-dev
+
+- Require version `8.3.0` of the `analyzer` package.
+- Improve error message when trying to use any of the built-in mock libraries
+  from a test outside of the Dart SDK.
+
 ## 0.1.3
 
 - Require version `8.2.0` of the `analyzer` package.

pkg/analyzer_testing/lib/mock_packages/mock_packages.dart

@@ -151,9 +151,16 @@ mixin MockPackagesMixin {
   Folder _addFiles(String packageName) {
     var cachedFiles = _cachedFiles;
     if (cachedFiles == null) {
-      cachedFiles = {};
-      _cacheFiles(cachedFiles);
-      _cachedFiles = cachedFiles;
+      try {
+        cachedFiles = {};
+        _cacheFiles(cachedFiles);
+        _cachedFiles = cachedFiles;
+      } on StateError catch (e) {
+        throw StateError(
+          '${e.message}\nAdding built-in mock library for "$packageName" is '
+          'not supported when writing a test outside of the Dart SDK source repository.',
+        );
+      }
     }
 
     for (var entry in cachedFiles.entries) {

pkg/analyzer_testing/lib/package_root.dart

@@ -41,7 +41,15 @@ String get packageRoot {
     return pathFromCwd;
   }
 
-  throw StateError('Unable to find sdk/pkg/ in $scriptPath');
+  var exceptionMessage =
+      'Unable to find the Dart SDK package root directory ("sdk/pkg/") in ';
+  if (pkgRootVar != null) {
+    exceptionMessage += '"$pkgRootVar" (specified via `-DpkgRoot=`), or ';
+  }
+  exceptionMessage +=
+      'in an ancestor of either "$pathFromScript", or "$pathFromCwd".';
+
+  throw StateError(exceptionMessage);
 }
 
 /// Tries to find the path to the 'pkg' folder from [searchPath].

pkg/analyzer_testing/pubspec.yaml

@@ -1,6 +1,6 @@
 name: analyzer_testing
 description: Testing utilities related to the analyzer and analysis_server_plugin packages.
-version: 0.1.3
+version: 0.1.4-dev
 repository: https://github.com/dart-lang/sdk/tree/main/pkg/analyzer_testing
 
 environment: