extract more information from package.json files; add tests (jsdoc#710)

lib/jsdoc/package.js

@@ -1,70 +1,228 @@
+'use strict';
+
+var logger = require('jsdoc/util/logger');
+
 /**
-    @overview
-    @author Michael Mathews <[email protected]>
-    @license Apache License 2.0 - See file 'LICENSE.md' in this project.
+ * Provides access to information about a JavaScript package.
+ *
+ * @module jsdoc/package
+ * @see https://www.npmjs.org/doc/files/package.json.html
+ */
+
+// Collect all of the license information from a `package.json` file.
+function getLicenses(packageInfo) {
+    var licenses = packageInfo.licenses ? packageInfo.licenses.slice(0) : [];
+
+    if (packageInfo.license) {
+        licenses.push({ type: packageInfo.license });
+    }
+
+    if (licenses.length) {
+        return licenses;
+    }
+}
+
+/**
+ * Information about where to report bugs in the package.
+ *
+ * @typedef {Object} module:jsdoc/package.Package~BugInfo
+ * @property {string} email - The email address for reporting bugs.
+ * @property {string} url - The URL for reporting bugs.
+ */
+
+/**
+ * Information about a package's software license.
+ *
+ * @typedef {Object} module:jsdoc/package.Package~LicenseInfo
+ * @property {string} type - An identifier for the type of license.
+ * @property {string} url - The URL for the complete text of the license.
+ */
+
+/**
+ * Information about a package author or contributor.
+ *
+ * @typedef {Object} module:jsdoc/package.Package~PersonInfo
+ * @property {string} name - The person's full name.
+ * @property {string} email - The person's email address.
+ * @property {string} url - The URL of the person's website.
  */
-'use strict';
 
 /**
-    @module jsdoc/package
-    @see http://wiki.commonjs.org/wiki/Packages/1.0
+ * Information about a package's version-control repository.
+ *
+ * @typedef {Object} module:jsdoc/package.Package~RepositoryInfo
+ * @property {string} type - The type of version-control system that the repository uses (for
+ * example, `git` or `svn`).
+ * @property {string} url - The URL for the repository.
  */
 
 /**
-    @class
-    @classdesc Represents a JavaScript package.
-    @param {string} json - The contents of package.json.
+ * Information about a JavaScript package. JSDoc can extract package information from
+ * `package.json` files that follow the
+ * [npm specification](https://www.npmjs.org/doc/files/package.json.html).
+ *
+ * **Note**: JSDoc does not validate or normalize the contents of `package.json` files. If your
+ * `package.json` file does not follow the npm specification, some properties of the `Package`
+ * object may not use the format documented here.
+ *
+ * @class
+ * @param {string} json - The contents of the `package.json` file.
  */
 exports.Package = function(json) {
-    json = json || '{}';
+    var packageInfo;
 
-    /** The source files associated with this package.
-        @type {Array<String>}
+    /**
+     * The string identifier that is shared by all `Package` objects.
+     *
+     * @readonly
+     * @default
+     * @type {string}
      */
-    this.files = [];
-
-    /** The kind of this package.
-        @readonly
-        @default
-        @type {string}
-    */
     this.kind = 'package';
 
-    json = JSON.parse(json);
+    try {
+        packageInfo = JSON.parse(json || '{}');
+    }
+    catch (e) {
+        logger.error('Unable to parse the package file: %s', e.message);
+        packageInfo = {};
+    }
 
-    /** The name of this package.
-        This value is found in the package.json file passed in as a command line option.
-        @type {string}
-    */
-    this.name = json.name;
+    /**
+     * The package name.
+     *
+     * @type {string}
+     */
+    this.name = packageInfo.name;
 
-    /** The longname of this package.
-        @type {string}
-    */
+    /**
+     * The unique longname for this `Package` object.
+     *
+     * @type {string}
+     */
     this.longname = this.kind + ':' + this.name;
 
-    /** The description of this package.
-        @type {string}
-    */
-    this.description = json.description;
+    /**
+     * The author of this package. Contains either a
+     * {@link module:jsdoc/package.Package~PersonInfo PersonInfo} object or a string with
+     * information about the author.
+     *
+     * @type {(module:jsdoc/package.Package~PersonInfo|string)}
+     * @since 3.3.0
+     */
+    this.author = packageInfo.author;
+
+    /**
+     * Information about where to report bugs in the project. May contain a URL, as a string, or
+     * an object with more detailed information.
+     *
+     * @type {(string|module:jsdoc/package.Package~BugInfo)}
+     * @since 3.3.0
+     */
+    this.bugs = packageInfo.bugs;
+
+    /**
+     * The contributors to this package.
+     *
+     * @type {Array.<(module:jsdoc/package.Package~PersonInfo|string)>}
+     * @since 3.3.0
+     */
+    this.contributors = packageInfo.contributors;
+
+    /**
+     * The dependencies for this package.
+     *
+     * @type {Object}
+     * @since 3.3.0
+     */
+    this.dependencies = packageInfo.dependencies;
+
+    /**
+     * A brief description of the package.
+     *
+     * @type {string}
+     */
+    this.description = packageInfo.description;
+
+    /**
+     * The development dependencies for this package.
+     *
+     * @type {Object}
+     * @since 3.3.0
+     */
+    this.devDependencies = packageInfo.devDependencies;
+
+    /**
+     * The JavaScript engines that this package supports. Each key is a string that identifies the
+     * engine (for example, `node`). Each value is a
+     * [semver](https://www.npmjs.org/doc/misc/semver.html)-compliant version number for the engine.
+     *
+     * @type {Object}
+     * @since 3.3.0
+     */
+    this.engines = packageInfo.engines;
+
+    /**
+     * The source files associated with the package.
+     *
+     * New `Package` objects always contain an empty array, regardless of whether the `package.json`
+     * file includes a `files` property.
+     *
+     * After JSDoc parses your input files, it sets this property to a list of paths to your input
+     * files.
+     *
+     * @type {Array.<string>}
+     */
+    this.files = [];
+
+    /**
+     * The URL for the package's homepage.
+     *
+     * @type {string}
+     * @since 3.3.0
+     */
+    this.homepage = packageInfo.homepage;
+
+    /**
+     * Keywords to help users find the package.
+     *
+     * @type {Array.<string>}
+     * @since 3.3.0
+     */
+    this.keywords = packageInfo.keywords;
 
     /**
-        The hash summary of the source file.
-        @type {string}
-        @since 3.2.0
-    */
-    this.version = json.version;
+     * The licenses used by this package. Combines information from the `package.json` file's
+     * `license` property and the deprecated `licenses` property.
+     *
+     * @type {Array.<module:jsdoc/package.Package~LicenseInfo>}
+     */
+    this.licenses = getLicenses(packageInfo);
+
+    /**
+     * The module ID that provides the primary entry point to the package. For example, if your
+     * package is a CommonJS module, and the value of this property is `foo`, users should be able
+     * to load your module with `require('foo')`.
+     *
+     * @type {string}
+     * @since 3.3.0
+     */
+    this.main = packageInfo.main;
+
+    /**
+     * The version-control repository for the package.
+     *
+     * @type {module:jsdoc/package.Package~RepositoryInfo}
+     * @since 3.3.0
+     */
+    this.repository = packageInfo.repository;
 
     /**
-     * The licenses of this package.
-     * @type {Array<Object>}
-     * @example
-     * "licenses": [
-     *     {
-     *        "type": "GPLv2",
-     *        "url": "http://www.example.com/licenses/gpl.html"
-     *     }
-     * ]
+     * The [semver](https://www.npmjs.org/doc/misc/semver.html)-compliant version number of the
+     * package.
+     *
+     * @type {string}
+     * @since 3.2.0
      */
-    this.licenses = json.licenses;
+    this.version = packageInfo.version;
 };