analyzer plugins: Document how to add a stub package in tests

Fixes #61915

I add documentation to a few APIs, and primarily document `newPackage`
and `PackageBuilder.addFile`, which already have sufficient doc
comments.

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

Author: srawlins

pkg/analysis_server_plugin/doc/testing_rules.md

@@ -148,4 +148,57 @@ running `dart test` or `dart --enable-asserts test/my_rule_test.dart`.
 
 [`analyzer_testing`]: https://pub.dev/packages/analyzer_testing
 [writing rules]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md
-[`test_reflective_loader`]: https://pub.dev/packages/test_reflective_loader
+[`test_reflective_loader`]: https://pub.dev/packages/test_reflective_loader
+
+## Writing stub package sources
+
+Often an analysis rule needs to understand if a type or an element (like a class
+or a method) is a specific type/element from a specific library in a package.
+For example, a rule might be concerned with the use of the `test` function
+declared in the `test_core` package. In order to write tests for such a rule,
+the test code needs to import something like
+`'package:test_core/test_core.dart'`. In order to make such an import
+meaningful, some stub code needs to be written so that, in fact, a `test`
+function is made available by that import.
+
+The [`AnalysisRuleTest`][] class offers a [`newPackage`][] method which supports
+writing code in other packages. `newPackage` returns a `PackageBuilder`, which
+is used to add individual library sources via its `addFile` method. For example,
+to write the sources for a stub `test` function in a package named `test_core`,
+you can:
+
+```dart
+class MyRuleTest extends AnalysisRuleTest {
+  @override
+  void setUp() {
+    newPackage('test_core')..addFile('lib/test_core.dart', r'''
+void test(
+  Object? description,
+  dynamic body(), {
+  String? testOn,
+  Object? /*Timeout?*/ timeout,
+  Object? skip,
+  Object? tags,
+  Map<String, dynamic>? onPlatform,
+  int? retry,
+  Object? /*TestLocation?*/ location,
+  bool solo = false,
+}) {}
+''');
+    super.setUp();
+  }
+}
+```
+
+Here are a few tips for writing stub package sources:
+
+* `newPackage` needs to be called in `setUp`, before the call to `super.setUp`.
+* For the static analysis purposes of testing analysis rules, it is unnecessary
+  to include function bodies (see the empty `test` body above).
+* It is often not necessary to include all of the types which are needed to
+  write a type or an element, like a function signature (see the `location`
+  parameter above, which is typed as an `Object?` instead of a `TestLocation?`).
+  This can greatly simplify the stubs.
+
+[`AnalysisRuleTest`]: https://pub.dev/documentation/analyzer_testing/latest/analysis_rule_analysis_rule/AnalysisRuleTest-class.html
+[`newPackage`]: https://pub.dev/documentation/analyzer_testing/latest/analysis_rule_analysis_rule/AnalysisRuleTest/newPackage.html

pkg/analyzer/lib/utilities/package_config_file_builder.dart

@@ -7,15 +7,22 @@ import 'package:path/path.dart' as path;
 /// Helper for building `.dart_tool/package_config.json` files.
 ///
 /// See accepted/future-releases/language-versioning/package-config-file-v2.md
-/// in https://github.com/dart-lang/language/
+/// in https://github.com/dart-lang/language/.
+///
+/// Use the [add] method to add package configurations. These configurations
+/// will accumulate into one package config file with the [toContent] method.
 class PackageConfigFileBuilder {
   final List<_PackageDescription> _packages = [];
 
   /// The [rootPath] will be given to `toUriStr` of [toContent] to produce
   /// the corresponding `file://` URI, normally a POSIX path.
   ///
-  /// The [packageUri] is optional, a URI reference, resolved against the
-  /// file URI of the [rootPath]. The result must be inside the [rootPath].
+  /// The [packageUri] is optional (defaults to `'lib/'`), a relative path
+  /// resolved against the file URI of the [rootPath]. The result must be inside
+  /// the [rootPath].
+  ///
+  /// The [languageVersion] specifies the package's Dart language version, in
+  /// the form of 'X.Y', such as '3.9'.
   void add({
     required String name,
     required String rootPath,

pkg/analyzer_testing/api.txt

@@ -12,6 +12,7 @@ package:analyzer_testing/analysis_rule/analysis_rule.dart:
     lint (method: ExpectedDiagnostic Function(int, int, {List<ExpectedContextMessage>? contextMessages, Pattern? correctionContains, deprecated Pattern? messageContains, List<Pattern> messageContainsAll, String? name}))
     setUp (method: void Function())
     unexpectedMessage (method: String Function(List<Diagnostic>))
+  PackageBuilder (non-public)
 package:analyzer_testing/experiments/experiments.dart:
   experimentsForTests (static getter: List<String>)
   experimentsForTests= (static setter: List<String>)

pkg/analyzer_testing/lib/analysis_rule/analysis_rule.dart

@@ -20,6 +20,9 @@ import 'package:analyzer_testing/src/analysis_rule/pub_package_resolution.dart';
 import 'package:analyzer_testing/utilities/utilities.dart';
 import 'package:meta/meta.dart';
 
+export 'package:analyzer_testing/src/analysis_rule/pub_package_resolution.dart'
+    show PackageBuilder;
+
 ExpectedContextMessage contextMessage(
   File file,
   int offset,

pkg/analyzer_testing/lib/resource_provider_mixin.dart

@@ -138,7 +138,11 @@ mixin ResourceProviderMixin {
     return newFile(path, content);
   }
 
-  /// Writes a `.dart_tool/package_config.json` file at [directoryPath].
+  /// Writes a `.dart_tool/package_config.json` file at [directoryPath],
+  /// returning the [File] object.
+  ///
+  /// See the documentation for [PackageConfigFileBuilder] for information on
+  /// how to add package configurations.
   File newPackageConfigJsonFileFromBuilder(
     String directoryPath,
     PackageConfigFileBuilder builder,