1 | ;
|
2 |
|
3 | var logger = require('jsdoc/util/logger');
|
4 |
|
5 | /**
|
6 | * Provides access to information about a JavaScript package.
|
7 | *
|
8 | * @module jsdoc/package
|
9 | * @see https://www.npmjs.org/doc/files/package.json.html
|
10 | */
|
11 |
|
12 | // Collect all of the license information from a `package.json` file.
|
13 | function getLicenses(packageInfo) {
|
14 | var licenses = packageInfo.licenses ? packageInfo.licenses.slice(0) : [];
|
15 |
|
16 | if (packageInfo.license) {
|
17 | licenses.push({ type: packageInfo.license });
|
18 | }
|
19 |
|
20 | return licenses;
|
21 | }
|
22 |
|
23 | /**
|
24 | * Information about where to report bugs in the package.
|
25 | *
|
26 | * @typedef {Object} module:jsdoc/package.Package~BugInfo
|
27 | * @property {string} email - The email address for reporting bugs.
|
28 | * @property {string} url - The URL for reporting bugs.
|
29 | */
|
30 |
|
31 | /**
|
32 | * Information about a package's software license.
|
33 | *
|
34 | * @typedef {Object} module:jsdoc/package.Package~LicenseInfo
|
35 | * @property {string} type - An identifier for the type of license.
|
36 | * @property {string} url - The URL for the complete text of the license.
|
37 | */
|
38 |
|
39 | /**
|
40 | * Information about a package author or contributor.
|
41 | *
|
42 | * @typedef {Object} module:jsdoc/package.Package~PersonInfo
|
43 | * @property {string} name - The person's full name.
|
44 | * @property {string} email - The person's email address.
|
45 | * @property {string} url - The URL of the person's website.
|
46 | */
|
47 |
|
48 | /**
|
49 | * Information about a package's version-control repository.
|
50 | *
|
51 | * @typedef {Object} module:jsdoc/package.Package~RepositoryInfo
|
52 | * @property {string} type - The type of version-control system that the repository uses (for
|
53 | * example, `git` or `svn`).
|
54 | * @property {string} url - The URL for the repository.
|
55 | */
|
56 |
|
57 | /**
|
58 | * Information about a JavaScript package. JSDoc can extract package information from
|
59 | * `package.json` files that follow the
|
60 | * [npm specification](https://www.npmjs.org/doc/files/package.json.html).
|
61 | *
|
62 | * **Note**: JSDoc does not validate or normalize the contents of `package.json` files. If your
|
63 | * `package.json` file does not follow the npm specification, some properties of the `Package`
|
64 | * object may not use the format documented here.
|
65 | *
|
66 | * @class
|
67 | * @param {string} json - The contents of the `package.json` file.
|
68 | */
|
69 | exports.Package = function(json) {
|
70 | var packageInfo;
|
71 |
|
72 | /**
|
73 | * The string identifier that is shared by all `Package` objects.
|
74 | *
|
75 | * @readonly
|
76 | * @default
|
77 | * @type {string}
|
78 | */
|
79 | this.kind = 'package';
|
80 |
|
81 | try {
|
82 | packageInfo = JSON.parse(json || '{}');
|
83 | }
|
84 | catch (e) {
|
85 | logger.error('Unable to parse the package file: %s', e.message);
|
86 | packageInfo = {};
|
87 | }
|
88 |
|
89 | if (packageInfo.name) {
|
90 | /**
|
91 | * The package name.
|
92 | *
|
93 | * @type {string}
|
94 | */
|
95 | this.name = packageInfo.name;
|
96 | }
|
97 |
|
98 | /**
|
99 | * The unique longname for this `Package` object.
|
100 | *
|
101 | * @type {string}
|
102 | */
|
103 | this.longname = this.kind + ':' + this.name;
|
104 |
|
105 | if (packageInfo.author) {
|
106 | /**
|
107 | * The author of this package. Contains either a
|
108 | * {@link module:jsdoc/package.Package~PersonInfo PersonInfo} object or a string with
|
109 | * information about the author.
|
110 | *
|
111 | * @type {(module:jsdoc/package.Package~PersonInfo|string)}
|
112 | * @since 3.3.0
|
113 | */
|
114 | this.author = packageInfo.author;
|
115 | }
|
116 |
|
117 | if (packageInfo.bugs) {
|
118 | /**
|
119 | * Information about where to report bugs in the project. May contain a URL, as a string, or
|
120 | * an object with more detailed information.
|
121 | *
|
122 | * @type {(string|module:jsdoc/package.Package~BugInfo)}
|
123 | * @since 3.3.0
|
124 | */
|
125 | this.bugs = packageInfo.bugs;
|
126 | }
|
127 |
|
128 | if (packageInfo.contributors) {
|
129 | /**
|
130 | * The contributors to this package.
|
131 | *
|
132 | * @type {Array.<(module:jsdoc/package.Package~PersonInfo|string)>}
|
133 | * @since 3.3.0
|
134 | */
|
135 | this.contributors = packageInfo.contributors;
|
136 | }
|
137 |
|
138 | if (packageInfo.dependencies) {
|
139 | /**
|
140 | * The dependencies for this package.
|
141 | *
|
142 | * @type {Object}
|
143 | * @since 3.3.0
|
144 | */
|
145 | this.dependencies = packageInfo.dependencies;
|
146 | }
|
147 |
|
148 | if (packageInfo.description) {
|
149 | /**
|
150 | * A brief description of the package.
|
151 | *
|
152 | * @type {string}
|
153 | */
|
154 | this.description = packageInfo.description;
|
155 | }
|
156 |
|
157 | if (packageInfo.devDependencies) {
|
158 | /**
|
159 | * The development dependencies for this package.
|
160 | *
|
161 | * @type {Object}
|
162 | * @since 3.3.0
|
163 | */
|
164 | this.devDependencies = packageInfo.devDependencies;
|
165 | }
|
166 |
|
167 | if (packageInfo.engines) {
|
168 | /**
|
169 | * The JavaScript engines that this package supports. Each key is a string that identifies the
|
170 | * engine (for example, `node`). Each value is a
|
171 | * [semver](https://www.npmjs.org/doc/misc/semver.html)-compliant version number for the engine.
|
172 | *
|
173 | * @type {Object}
|
174 | * @since 3.3.0
|
175 | */
|
176 | this.engines = packageInfo.engines;
|
177 | }
|
178 |
|
179 | /**
|
180 | * The source files associated with the package.
|
181 | *
|
182 | * New `Package` objects always contain an empty array, regardless of whether the `package.json`
|
183 | * file includes a `files` property.
|
184 | *
|
185 | * After JSDoc parses your input files, it sets this property to a list of paths to your input
|
186 | * files.
|
187 | *
|
188 | * @type {Array.<string>}
|
189 | */
|
190 | this.files = [];
|
191 |
|
192 | if (packageInfo.homepage) {
|
193 | /**
|
194 | * The URL for the package's homepage.
|
195 | *
|
196 | * @type {string}
|
197 | * @since 3.3.0
|
198 | */
|
199 | this.homepage = packageInfo.homepage;
|
200 | }
|
201 |
|
202 | if (packageInfo.keywords) {
|
203 | /**
|
204 | * Keywords to help users find the package.
|
205 | *
|
206 | * @type {Array.<string>}
|
207 | * @since 3.3.0
|
208 | */
|
209 | this.keywords = packageInfo.keywords;
|
210 | }
|
211 |
|
212 | if (packageInfo.license || packageInfo.licenses) {
|
213 | /**
|
214 | * The licenses used by this package. Combines information from the `package.json` file's
|
215 | * `license` property and the deprecated `licenses` property.
|
216 | *
|
217 | * @type {Array.<module:jsdoc/package.Package~LicenseInfo>}
|
218 | */
|
219 | this.licenses = getLicenses(packageInfo);
|
220 | }
|
221 |
|
222 | if (packageInfo.main) {
|
223 | /**
|
224 | * The module ID that provides the primary entry point to the package. For example, if your
|
225 | * package is a CommonJS module, and the value of this property is `foo`, users should be able
|
226 | * to load your module with `require('foo')`.
|
227 | *
|
228 | * @type {string}
|
229 | * @since 3.3.0
|
230 | */
|
231 | this.main = packageInfo.main;
|
232 | }
|
233 |
|
234 | if (packageInfo.repository) {
|
235 | /**
|
236 | * The version-control repository for the package.
|
237 | *
|
238 | * @type {module:jsdoc/package.Package~RepositoryInfo}
|
239 | * @since 3.3.0
|
240 | */
|
241 | this.repository = packageInfo.repository;
|
242 | }
|
243 |
|
244 | if (packageInfo.version) {
|
245 | /**
|
246 | * The [semver](https://www.npmjs.org/doc/misc/semver.html)-compliant version number of the
|
247 | * package.
|
248 | *
|
249 | * @type {string}
|
250 | * @since 3.2.0
|
251 | */
|
252 | this.version = packageInfo.version;
|
253 | }
|
254 | };
|