fail gracefully when no pubspec is found

Closes #741

LGTM given by: @sethladd

Squashed commit of the following:

commit b1e7343
Author: Seth Ladd <[email protected]>
Date:   Tue Jul 28 10:16:45 2015 -0700

    fail gracefully when no pubspec is found

Author: sethladd

bin/dartdoc.dart

@@ -104,6 +104,12 @@ main(List<String> arguments) async {
       ? new PackageMeta.fromSdk(sdkDir, sdkReadmePath: readme)
       : new PackageMeta.fromDir(inputDir);
 
+  if (!packageMeta.isValid) {
+    print('Unable to generate documentation.');
+    packageMeta.getInvalidReasons().map((r) => '* $r').forEach(print);
+    exit(1);
+  }
+
   print("Generating documentation for '${packageMeta}' into "
       "${outputDir.absolute.path}${Platform.pathSeparator}");
   print('');

lib/src/package_meta.dart

@@ -29,6 +29,15 @@ abstract class PackageMeta {
   FileContents getLicenseContents();
   FileContents getChangelogContents();
 
+  /// Returns true if we are a valid package, valid enough to generate docs.
+  bool get isValid;
+
+  /// Returns a list of reasons this package is invalid, or an
+  /// empty list if no reasons found.
+  ///
+  /// If the list is empty, this package is valid.
+  List<String> getInvalidReasons();
+
   String toString() => name;
 }
 
@@ -89,6 +98,22 @@ class _FilePackageMeta extends PackageMeta {
         _locate(dir, ['changelog.md', 'changelog.txt', 'changelog']));
     return _changelog;
   }
+
+  @override
+  bool get isValid => getInvalidReasons().isEmpty;
+
+  /// Returns a list of reasons this package is invalid, or an
+  /// empty list if no reasons found.
+  @override
+  List<String> getInvalidReasons() {
+    var reasons = [];
+    if (_pubspec == null || _pubspec.isEmpty) {
+      reasons.add('No pubspec.yaml found');
+    } else if (!_pubspec.containsKey('name')) {
+      reasons.add('No name found in pubspec.yaml');
+    }
+    return reasons;
+  }
 }
 
 File _locate(Directory dir, List<String> fileNames) {
@@ -127,6 +152,12 @@ class _SdkMeta extends PackageMeta {
     return f.existsSync() ? new FileContents(f) : null;
   }
 
+  @override
+  bool get isValid => true;
+
+  @override
+  List<String> getInvalidReasons() => [];
+
   FileContents getLicenseContents() => null;
 
   // TODO: The changelog doesn't seem to be available in the sdk.

test/package_meta_test.dart

@@ -9,8 +9,28 @@ import 'dart:io';
 import 'package:cli_util/cli_util.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:test/test.dart';
+import 'package:path/path.dart' as path;
 
 void main() {
+  group('PackageMeta for a directory without a pubspec', () {
+    PackageMeta p;
+
+    setUp(() {
+      var d = new Directory(
+          path.join(Directory.current.path, 'test_package_not_valid'));
+      if (!d.existsSync()) {
+        throw "$d cannot be found";
+      }
+      p = new PackageMeta.fromDir(d);
+    });
+
+    test('is not valid', () {
+      expect(p.isValid, isFalse);
+      expect(p.getInvalidReasons(), isNotEmpty);
+      expect(p.getInvalidReasons(), contains('No pubspec.yaml found'));
+    });
+  });
+
   group('PackageMeta.fromDir for this package', () {
     PackageMeta p = new PackageMeta.fromDir(Directory.current);
 
@@ -30,6 +50,11 @@ void main() {
       expect(p.homepage, equals('https://github.com/dart-lang/dartdoc'));
     });
 
+    test('is valid', () {
+      expect(p.isValid, isTrue);
+      expect(p.getInvalidReasons(), isEmpty);
+    });
+
     test('has a readme', () {
       expect(p.getReadmeContents(), isNotNull);
       expect(p.getReadmeContents().contents, contains('''
@@ -56,6 +81,11 @@ generated from Dart source code.'''));
       expect(p.name, 'Dart SDK');
     });
 
+    test('is valid', () {
+      expect(p.isValid, isTrue);
+      expect(p.getInvalidReasons(), isEmpty);
+    });
+
     test('has a version', () {
       expect(p.version, isNotNull);
     });

test_package/lib/fake.dart

@@ -350,3 +350,6 @@ class WithGetterAndSetter {
   /// Throws if set to an imaginary number.
   void set lengthX(int _length) {}
 }
+
+/// I have a generic and it extends [Foo2]
+class HasGenericWithExtends<T extends Foo2> {}

test_package_not_valid/README.md

@@ -0,0 +1,6 @@
+# Does not contain a pubspec.yaml
+
+This will fail, because dartdoc currently requires
+a pubspec.yaml file to run.
+
+We can revisit that decision.