Add arbitrary pub package serving to grinder and ignore URI_HAS_NOT_BEEN_GENERATED (#1599)

* first version, start of tests

* pubspec change

* add grinder tools to CONTRIBUTING

* review comment

* remove unused function

Author: jcollins-g

CONTRIBUTING.md

@@ -24,8 +24,31 @@ yet in the issue tracker, start by opening an issue. Thanks!
 1. `grind` is needed to run dartdoc integration tests, see installed via `pub global activate grinder`.
 2. When a change is user-facing, please add a new entry to the [changelog](https://github.com/dart-lang/dartdoc/blob/master/CHANGELOG.md)
 3. Please include a test for your change.  `dartdoc` has both `package:test`-style unittests as well as integration tests.  To run the unittests, use `dart test/all.dart`.  Most changes can be tested via a unittest, but some require modifying the [test_package](https://github.com/dart-lang/dartdoc/tree/master/testing/test_package) and regenerating its docs via `grind update-test-package-docs`.
-4.  Be sure to format your Dart code using `dartfmt -w`, otherwise travis will complain.
-5.  Post your change via a pull request for review and integration!
+4. For major changes, run `grind compare-sdk-warnings` and include the summary results in your pull request.
+5.  Be sure to format your Dart code using `dartfmt -w`, otherwise travis will complain.
+6.  Post your change via a pull request for review and integration!
+
+## Testing
+
+dartdoc has a number of grinder utility methods that can be used to check for behavior changes
+or try out your change on arbitrary packages. 
+
+```bash
+# Serve the latest version of the given package locally on port 9000.
+PACKAGE_NAME=angular_components grind serve-pub-package
+
+# Build the SDK docs with the head version and compare its warning
+# output and (rough) performance to the main version.
+grind compare-sdk-warnings
+
+# Serve the flutter docs built with the head version on port 8001.
+grind serve-flutter-docs
+
+# Serve the test package (testing/test_package) on port 8002
+grind serve-test-package-docs
+```
+
+There are more added all the time -- run `grind --help` to see them all.
 
 ## License
 

lib/dartdoc.dart

@@ -131,6 +131,8 @@ class DartDoc extends PackageBuilder {
               new _Error(error, info.lineInfo, packageMeta.dir.path));
         })
         .where((_Error error) => error.isError)
+        // TODO(jcollins-g): remove after conversion to analysis driver
+        .where((_Error error) => error.error.errorCode != CompileTimeErrorCode.URI_HAS_NOT_BEEN_GENERATED)
         .toList()
           ..sort();
 

lib/src/io_utils.dart

@@ -67,9 +67,7 @@ final RegExp quotables = new RegExp(r'[ "\r\n\$]');
 
 class SubprocessLauncher {
   final String context;
-  Map<String, String> _environment;
-
-  Map<String, String> get environment => _environment;
+  final Map<String, String> environment;
 
   String get prefix => context.isNotEmpty ? '$context: ' : '';
 
@@ -90,13 +88,8 @@ class SubprocessLauncher {
     });
   }
 
-  SubprocessLauncher(this.context, [Map<String, String> environment]) {
-    if (environment == null) {
-      this._environment = new Map();
-    } else {
-      this._environment = environment;
-    }
-  }
+  SubprocessLauncher(this.context, [Map<String, String> environment]) :
+      this.environment = environment ?? <String, String>{};
 
   /// A wrapper around start/await process.exitCode that will display the
   /// output of the executable continuously and fail on non-zero exit codes.

pubspec.lock

@@ -415,4 +415,4 @@ packages:
     source: hosted
     version: "2.1.13"
 sdks:
-  dart: ">=1.23.0 <=2.0.0-dev.16.0"
+  dart: ">=1.23.0 <=2.0.0-dev.20.0"

tool/grind.dart

@@ -200,6 +200,21 @@ Future serveTestPackageDocs() async {
   ]);
 }
 
+_serveDocsFrom(String servePath, int port, String context) async {
+  log('launching dhttpd on port $port for $context');
+  var launcher = new SubprocessLauncher(context);
+  await launcher.runStreamed(sdkBin('pub'), ['get']);
+  await launcher.runStreamed(sdkBin('pub'), ['global', 'activate', 'dhttpd']);
+  await launcher.runStreamed(sdkBin('pub'), [
+    'run',
+    'dhttpd',
+    '--port',
+    '$port',
+    '--path',
+    servePath
+  ]);
+}
+
 @Task('Serve generated SDK docs locally with dhttpd on port 8000')
 @Depends(buildSdkDocs)
 Future serveSdkDocs() async {
@@ -279,6 +294,38 @@ Future _buildFlutterDocs(String flutterPath, [String label]) async {
   );
 }
 
+/// Returns the directory in which we generated documentation.
+Future<String> _buildPubPackageDocs(String pubPackageName, [String version, String label]) async {
+  Map<String, String> env = _createThrowawayPubCache();
+  var launcher = new SubprocessLauncher(
+       'build-${pubPackageName}${version == null ? "" : "-$version"}${label == null ? "" : "-$label"}', env);
+  List<String> args = <String>['cache', 'add'];
+  if (version != null) args.addAll(<String>['-v', version]);
+  args.add(pubPackageName);
+  await launcher.runStreamed('pub', args);
+  Directory cache = new Directory(path.join(env['PUB_CACHE'], 'hosted', 'pub.dartlang.org'));
+  Directory pubPackageDir = cache.listSync().firstWhere((e) => e.path.contains(pubPackageName));
+  await launcher.runStreamed('pub', ['get'], workingDirectory: pubPackageDir.absolute.path);
+  await launcher.runStreamed(
+      Platform.resolvedExecutable,
+      [
+        '--checked',
+        path.join(Directory.current.absolute.path, 'bin', 'dartdoc.dart'),
+        '--json',
+        '--show-progress',
+      ],
+      workingDirectory: pubPackageDir.absolute.path);
+  return path.join(pubPackageDir.absolute.path, 'doc', 'api');
+}
+
+@Task('Serve an arbitrary pub package based on PACKAGE_NAME and PACKAGE_VERSION environment variables')
+servePubPackage() async {
+  assert(Platform.environment.containsKey('PACKAGE_NAME'));
+  String packageName = Platform.environment['PACKAGE_NAME'];
+  String version = Platform.environment['PACKAGE_VERSION'];
+  _serveDocsFrom(await _buildPubPackageDocs(packageName, version), 9000, 'serve-pub-package');
+}
+
 @Task('Checks that CHANGELOG mentions current version')
 checkChangelogHasVersion() async {
   var changelog = new File('CHANGELOG.md');