Check if dartdoc can run on the package.

Author: isoos

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 * `ToolEnvironment.runAnalyzer` returns the text output of the process.
 
+Updates:
+
+* Check if `dartdoc` can run on the package.
+
 ## 0.10.6
 
 * Enable Dart 2 Preview in analyzer options (including non-Flutter packages).

lib/src/maintenance.dart

@@ -164,6 +164,7 @@ Future<Maintenance> detectMaintenance(
   List<Suggestion> dartFileSuggestions,
   List<PkgDependency> unconstrainedDeps, {
   @required DartPlatform pkgPlatform,
+  @required bool dartdocSuccessful,
 }) async {
   final pkgName = pubspec.name;
   final maintenanceSuggestions = <Suggestion>[];
@@ -217,6 +218,14 @@ Future<Maintenance> detectMaintenance(
     }
   }
 
+  if (!dartdocSuccessful) {
+    maintenanceSuggestions.add(new Suggestion.error(
+      'Running `dartdoc` failed.',
+      'Make sure `dartdoc` runs without any issues.',
+      penalty: new Penalty(fraction: 1000),
+    ));
+  }
+
   if (pkgPlatform.hasConflict) {
     maintenanceSuggestions.add(new Suggestion.error(
         'Fix platform conflicts.', pkgPlatform.reason,

lib/src/package_analyzer.dart

@@ -176,6 +176,15 @@ class PackageAnalyzer {
 
     Set<CodeProblem> analyzerItems;
 
+    var dartdocSuccessful = false;
+    if (pkgResolution != null) {
+      try {
+        dartdocSuccessful = await _toolEnv.checkDartdoc(pkgDir);
+      } catch (e, st) {
+        log.severe('Could not run dartdoc.', e, st);
+      }
+    }
+
     if (pkgResolution != null) {
       try {
         var overrides = [
@@ -314,6 +323,7 @@ class PackageAnalyzer {
       dartFileSuggestions,
       pkgResolution?.getUnconstrainedDeps(onlyDirect: true),
       pkgPlatform: platform,
+      dartdocSuccessful: dartdocSuccessful,
     );
     suggestions.sort();
 

lib/src/sdk_env.dart

@@ -22,9 +22,11 @@ class ToolEnvironment {
   final String _pubCmd;
   final String _dartAnalyzerCmd;
   final String _dartfmtCmd;
+  final String _dartdocCmd;
   final String _flutterCmd;
   final Map<String, String> _environment;
   DartSdkInfo _dartSdkInfo;
+  bool _useGlobalDartdoc;
 
   ToolEnvironment._(
     this.dartSdkDir,
@@ -33,8 +35,10 @@ class ToolEnvironment {
     this._pubCmd,
     this._dartAnalyzerCmd,
     this._dartfmtCmd,
+    this._dartdocCmd,
     this._flutterCmd,
     this._environment,
+    this._useGlobalDartdoc,
   );
 
   DartSdkInfo get dartSdkInfo => _dartSdkInfo;
@@ -51,6 +55,7 @@ class ToolEnvironment {
     String flutterSdkDir,
     String pubCacheDir,
     Map<String, String> environment,
+    bool useGlobalDartdoc: false,
   }) async {
     Future<String> resolve(String dir) async {
       if (dir == null) return null;
@@ -65,7 +70,7 @@ class ToolEnvironment {
     env.addAll(environment ?? const {});
 
     if (resolvedPubCache != null) {
-      env['PUB_CACHE'] = resolvedPubCache;
+      env[_pubCacheKey] = resolvedPubCache;
     }
 
     final pubEnvValues = <String>[];
@@ -84,8 +89,10 @@ class ToolEnvironment {
       _join(resolvedDartSdk, 'bin', 'pub'),
       _join(resolvedDartSdk, 'bin', 'dartanalyzer'),
       _join(resolvedDartSdk, 'bin', 'dartfmt'),
+      _join(resolvedDartSdk, 'bin', 'dartdoc'),
       _join(resolvedFlutterSdk, 'bin', 'flutter'),
       env,
+      useGlobalDartdoc,
     );
     await toolEnv._init();
     return toolEnv;
@@ -227,6 +234,45 @@ class ToolEnvironment {
     return result;
   }
 
+  Map<String, String> _globalDartdocEnv() {
+    final env = new Map<String, String>.from(_environment);
+    if (pubCacheDir != null) {
+      env.remove(_pubCacheKey);
+    }
+    return env;
+  }
+
+  Future activateGlobalDartdoc(String version) async {
+    handleProcessErrors(await runProc(
+      _pubCmd,
+      ['global', 'activate', 'dartdoc', version],
+      environment: _globalDartdocEnv(),
+    ));
+    _useGlobalDartdoc = true;
+  }
+
+  Future<bool> checkDartdoc(String packageDir) async {
+    ProcessResult pr;
+    final args = ['--exclude', dartdocExcludedLibraries.join(',')];
+    if (_useGlobalDartdoc) {
+      pr = await runProc(
+        _pubCmd,
+        ['global', 'run', 'dartdoc']..addAll(args),
+        workingDirectory: packageDir,
+        environment: _globalDartdocEnv(),
+      );
+    } else {
+      pr = await runProc(
+        _dartdocCmd,
+        args,
+        workingDirectory: packageDir,
+        environment: _environment,
+      );
+    }
+    // TODO: check generated content e.g. index.html and index.json
+    return pr.exitCode == 0;
+  }
+
   Future<PackageLocation> getLocation(String package, {String version}) async {
     var args = ['cache', 'add', '--verbose'];
     if (version != null) {
@@ -326,9 +372,23 @@ class PackageLocation {
   PackageLocation(this.package, this.version, this.location);
 }
 
+const dartdocExcludedLibraries = const <String>[
+  'dart:async',
+  'dart:collection',
+  'dart:convert',
+  'dart:core',
+  'dart:developer',
+  'dart:io',
+  'dart:isolate',
+  'dart:math',
+  'dart:typed_data',
+  'dart:ui',
+];
+
 final _versionDownloadRegexp =
     new RegExp(r"^MSG : (?:Downloading |Already cached )([\w-]+) (.+)$");
 
+const _pubCacheKey = 'PUB_CACHE';
 const _pubEnvironmentKey = 'PUB_ENVIRONMENT';
 
 String _join(String path, String binDir, String executable) =>

test/end2end/skiplist_data.dart

@@ -285,6 +285,12 @@ final _data = {
     'warningCount': 0,
     'hintCount': 1,
     'suggestions': [
+      {
+        'level': 'error',
+        'title': 'Running `dartdoc` failed.',
+        'description': 'Make sure `dartdoc` runs without any issues.',
+        'penalty': {'amount': 0, 'fraction': 1000},
+      },
       {
         'level': 'warning',
         'title': 'Fix analysis and formatting issues.',

test/end2end/stream_broken_data.dart

@@ -56,6 +56,12 @@ final _data = {
             'Error(s) prevent platform classification:\n\nMake sure `dartfmt` runs.',
         'penalty': {'amount': 0, 'fraction': 2000}
       },
+      {
+        'level': 'error',
+        'title': 'Running `dartdoc` failed.',
+        'description': 'Make sure `dartdoc` runs without any issues.',
+        'penalty': {'amount': 0, 'fraction': 1000},
+      },
       {
         'level': 'warning',
         'title': 'Maintain `CHANGELOG.md`.',

test/maintenance_test.dart

@@ -31,6 +31,12 @@ final _withIssuesJson = {
       'description': 'conflict description',
       'penalty': {'amount': 0, 'fraction': 2000}
     },
+    {
+      'level': 'error',
+      'title': 'Running `dartdoc` failed.',
+      'description': 'Make sure `dartdoc` runs without any issues.',
+      'penalty': {'amount': 0, 'fraction': 1000},
+    },
     {
       'level': 'warning',
       'title': 'Maintain `CHANGELOG.md`.',
@@ -119,6 +125,7 @@ void main() {
         suggestions,
         [new PkgDependency('foo', 'direct', 'empty', null, null, null, null)],
         pkgPlatform: new DartPlatform.conflict('conflict description'),
+        dartdocSuccessful: false,
       );
 
       expect(json.decode(json.encode(maintenance.toJson())), _withIssuesJson);
@@ -127,7 +134,7 @@ void main() {
 
   group('getMaintenanceScore', () {
     test('with issues', () {
-      expect(_withIssues.getMaintenanceScore(), closeTo(0.530, 0.001));
+      expect(_withIssues.getMaintenanceScore(), closeTo(0.476, 0.001));
     });
 
     test('perfect', () {