grunt-jsdoc - npm Package Compare versions

Comparing version 0.2.4 to 0.3.0

Gruntfile.js

@@ -8,3 +8,3 @@ module.exports = function(grunt) {
 		dist: {
-			src: ['tasks/*.js', 'test/*_test.js'],
+			src: ['tasks/**.js', 'tasks/lib/*.js'],
 			options: {
@@ -19,3 +19,3 @@ destination: 'doc'
 	jshint : {
-		files : ['grunt.js', 'tasks/*.js', 'test/*.js'],
+		files : ['Gruntfile.js', 'tasks/*.js', 'tasks/lib/*.js', 'test/*.js'],
 		options: {
@@ -22,0 +22,0 @@ node : true,

package.json

 {
   "name": "grunt-jsdoc",
   "description": "Integrates jsdoc3 generation into your Grunt build",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "homepage": "https://github.com/krampstudio/grunt-jsdoc-plugin",
@@ -38,3 +38,3 @@ "author": {
   "dependencies": {
-    "jsdoc3": "git+https://github.com/jsdoc3/jsdoc.git#v3.1.1"
+    "jsdoc3": "git+https://github.com/jsdoc3/jsdoc.git#cfff8dd035ad376892139192c03718ce2dcc20f0"
   },
@@ -41,0 +41,0 @@ "peerDependencies" : {

README.md

@@ -19,3 +19,3 @@ # grunt-jsdoc-plugin [![Build Status](https://travis-ci.org/krampstudio/grunt-jsdoc-plugin.png)](https://travis-ci.org/krampstudio/grunt-jsdoc-plugin)
 ```bash
-npm install grunt-jsdoc
+npm install grunt-jsdoc --save-dev
 ```
@@ -43,3 +43,3 @@
             src: ['src/*.js', 'test/*.js'], 
-            options{
+            options: {
                 destination: 'doc'
@@ -56,7 +56,7 @@ }
  * `dest` : (deprecated) to support the previous way to set up destination folder
- * `jsdoc`: (optional) the path to the jsdoc bin (needed only for some boreder line cases)
+ * `jsdoc`: (optionnal) the path to the jsdoc bin (needed only for some boreder line cases)
  * `options` : options used by jsdoc 
    * `destination`: (required) the folder where the doc is generated
-   * `congif` : (optionnal) path to a config file
-   * `template` : (optionnal)path or name to a different template
+   * `configuration` : (optionnal) path to a config file
+   * `template` : (optionnal) path or name to a different template
    * `private` : (optionnal) include the private functions to the doc (`true` by default).
@@ -68,3 +68,3 @@ * ... refer the [usejsdocCli] documentation for all the available options.
 ```javascript
-grunt.loadNpmTasks('grunt-contrib-jsdoc');
+grunt.loadNpmTasks('grunt-jsdoc');
 ```
@@ -93,7 +93,11 @@
 
-Any contribution is welcome! Please check the [issues](https://github.com/krampstudio/grunt-jsdoc-plugin/issues).
+Any contribution is welcome! Please check the [issues](https://github.com/krampstudio/grunt-jsdoc-plugin/issues). Do some unit tests as far as possible.
 
 ## Release History
-
-
+ * _0.3.0_ Partial rewrite, Fix [bug #29](https://github.com/krampstudio/grunt-jsdoc-plugin/pull/30) and minor typos fixs 
+ * _0.2.0_ Migrate to grunt 0.4
+   * _0.2.1_ Fix [bug #10](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/10)
+   * _0.2.2_ Fix [bug #11](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/11)
+   * _0.2.3_ Fix [bug #14](https://github.com/krampstudio/grunt-jsdoc-plugin/pull/14) and [bug #15](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/15)
+   * _0.2.4_ Fix Jsdoc 3 dependency to 3.1.1 tag, enables jsdoc options [issue #19](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/19), enable to add jsdoc path [issue #13](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/13) and add peerDependencies
  * _0.1.0_ First release, includes basic support of [jsdoc3]
@@ -104,7 +108,3 @@ * _0.1.1_ Fix [bug #2](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/2)
    * _0.1.4_ Use `child_process.spawn` instead of `exec` to run the command
- * _0.2.0_ Migrate to grunt 0.4
-   * _0.2.1_ Fix [bug #10](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/10)
-   * _0.2.2_ Fix [bug #11](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/11)
-   * _0.2.3_ Fix [bug #14](https://github.com/krampstudio/grunt-jsdoc-plugin/pull/14) and [bug #15](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/15)
-   * _0.2.4_ Fix Jsdoc 3 dependency to 3.1.1 tag, enables jsdoc options [issue #19](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/19), enable to add jsdoc path [issue #13](https://github.com/krampstudio/grunt-jsdoc-plugin/issues/13) and add peerDependencies
+ 
 
@@ -111,0 +111,0 @@ [jsdoc3]: https://github.com/jsdoc3/jsdoc

tasks/jsdoc-plugin.js

@@ -6,3 +6,3 @@ /**
  * @license MIT
- * 
+ *
  * @module tasks/jsdoc-plugin
@@ -13,4 +13,4 @@ */
  * Register the jsdoc task and helpers to Grunt
+ * @type GruntTask
  * @constructor
- * @type GruntTask
  * @param {Object} grunt - the grunt context
@@ -22,14 +22,14 @@ */
 	var util = require('util'),
-	    errorCode = {
+			errorCode = {
 			generic : 1,
-			task	: 3	
+			task	: 3
 		};
 
 	/**
-     * Register the jsdoc task to Grunt
-     * @memberOf module:tasks/jsdoc-plugin
-     */
+	 * Register the jsdoc task to Grunt
+	 */
 	function registerJsdocTask() {
 		var fs				= require('fs'),
 			path			= require('path'),
+			exec			= require('./lib/exec'),
 			options			= grunt.task.current.options({'private': true}),
@@ -40,6 +40,9 @@ done			= grunt.task.current.async(),
 			jsDocPath		= grunt.task.current.data.jsdoc,
-			jsDocNpmPath	= 'node_modules/jsdoc/jsdoc',  
+			jsDocNpmPath	= 'node_modules/jsdoc/jsdoc',
 			timeout			= 60000,	//todo implement and move in options
+			cliFlags = ['recurse', 'private', 'lenient', 'explain', 'help', 'version', 'test', 'verbose', 'nocolor', 'template', 'configure', 'destination', 'encoding', 'tutorials'],
 			jsDoc;
 
+		//validate options
+		
 		if (!options.destination) {
@@ -50,73 +53,20 @@ // Support for old syntax where destination was provided through 'dest' key
 
-		/**
-		 * Build and execute a child process using the spawn function
-		 * @memberOf module:tasks/jsdoc-plugin
-		 * @param {String} script - the script to run
-		 * @param {Array} sources - the list of sources files 
-		 * @param {Object} options - the list of JSDoc options
-		 * @return {ChildProcess}  from the spawn
-		 */
-		var buildSpawned = function(script, sources, options){
-			var isWin = process.platform === 'win32',
-				cmd = (isWin) ? 'cmd' : script,
-				args = (isWin) ? ['/c', script] : [],
-				spawn = require('child_process').spawn;
-			
-			// Compute JSDoc options
-			for (var optionName in options) {
-				grunt.log.debug("Reading option: " + optionName);
-				args.push('--' + optionName);
-				if (options.hasOwnProperty(optionName) && typeof(options[optionName]) === 'string') {
-					grunt.log.debug("                > " + options[optionName]);
-					args.push(options[optionName]);
-				}
+		//legacy configs
+		if(options.config){
+			options.configure = options.config;
+		}
+
+		// Compute JSDoc flags from options
+		for(var optionName in options){
+			var option = options[optionName];
+			if(!grunt.util._.contains(cliFlags, optionName) || !options){
+				delete options[optionName];
 			}
+		}
 
-			if(!util.isArray(sources)){
-				sources = [sources];
-			} 
-			args.push.apply(args, sources);
-			
-			grunt.log.debug("Running : "+ cmd + " " + args.join(' '));
-			
-			return spawn(cmd, args);
-		};
+		grunt.log.debug(util.inspect(options));
 
-		/**
-		 * Lookup for the jsdoc executable throught the different configurations
-		 * @todo find a more elegant way to do that...
-		 * @memberOf module:tasks/jsdoc-plugin
-		 * @param {String} base - the base path of jsdoc to look up in the different directories
-		 * @param {String} [path] - a defined path to the jsdoc bin, in case of a non standard location
-		 * @returns {String} the command absolute path
-		 */
-		var jsDocLookup = function(base, extPath){
-			
-			var paths = [],
-				nodePath = process.env.NODE_PATH || '',
-				_ = grunt.util._;
+		//lookup jsdoc
+		jsDoc = exec.lookup(grunt, jsDocNpmPath, ['node_modules/grunt-jsdoc/', jsDocPath]);
 
-			if(extPath && typeof extPath === 'string'){
-				paths.push(extPath);
-			}
-			paths.push(base);
-			paths.push('node_modules/grunt-jsdoc/' + base);
-
-			_.map(nodePath.split(':'), function(p){
-				if(!/\/$/.test(p)){
-					p += '/';
-				}
-				paths.push(p + base);
-			});
-		
-			for(var i in paths){
-				grunt.log.debug('look up jsdoc at ' + paths[i]);
-				if(fs.existsSync(paths[i])){
-					//get the absolute path
-					return path.resolve(paths[i]);
-				}
-			}
-		};
-		jsDoc = jsDocLookup(jsDocNpmPath, jsDocPath);
-
 		//check if java is set
@@ -145,7 +95,7 @@ if(!javaHome){
 		//check if jsdoc config file path is provided and does exist
-		if (options.config && !fs.existsSync(options.config)){
+		if (options.configure && !fs.existsSync(options.configure)){
 			grunt.log.error('jsdoc config file path does not exist');
 			grunt.fail.warn('Wrong configuration', errorCode.generic);
 		}
-
+		
 		fs.exists(options.destination, function(exists){
@@ -155,6 +105,7 @@ //if the destination don't exists, we create it
 				grunt.file.mkdir(options.destination);
+				grunt.log.debug('create destination : ' + options.destination);
 			}
 
 			//execution of the jsdoc command
-			var child = buildSpawned(jsDoc, srcs, options);
+			var child = exec.buildSpawned(grunt, jsDoc, srcs, options);
 			child.stdout.on('data', function (data) {
@@ -166,3 +117,3 @@ grunt.log.debug('jsdoc output : ' + data);
 				grunt.fail.warn('jsdoc failure', errorCode.task);
-			});	
+			});
 			child.on('exit', function(code){
@@ -169,0 +120,0 @@ if(code === 0){

test/jsdoc-plugin_test.js

@@ -20,5 +20,5 @@ /**
  * the declared arguments from a function.
- * @param {function} fn - the function to extract the arguments for
- * @returns {array} the list of arguments
- * @throw {error} in case of wrong argument given
+ * @param {Function} fn - the function to extract the arguments for
+ * @returns {Array} the list of arguments
+ * @throw {Error} in case of wrong argument given
  */
@@ -70,3 +70,22 @@ var extractArgs = function(fn){
 		test.done();
+	}, 
+
+	/**
+	 * Do some check on the exec library
+	 * @memberOf JsdocTest
+	 * @param {Object} test - the node unit test context
+	 */
+	'execCheck' : function(test){
+		'use strict';	
+
+		var exec  = require('../tasks/lib/exec');
+
+		test.notStrictEqual(exec, undefined, 'the exec lib should be required');
+		test.equal(typeof exec, 'object', 'exec is an object');	
+
+		test.equal(typeof exec.buildSpawned, 'function', 'exec must have a buildSpawned method');	
+		test.equal(typeof exec.lookup, 'function', 'exec must have a lookup method');	
+		
+		test.done();
 	}
 };

New alerts

Git dependency

Supply chain risk

Contains a dependency which resolves to a remote git URL. Dependencies fetched from git URLs are not immutable and can be used to inject untrusted code or reduce the likelihood of a reproducible install.

Found 1 instance in 1 package

Fixed alerts

Git dependency

Supply chain risk

Contains a dependency which resolves to a remote git URL. Dependencies fetched from git URLs are not immutable and can be used to inject untrusted code or reduce the likelihood of a reproducible install.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

127232

increased by20.71%

Number of package files

32

increased by18.52%

Lines of code

1184

increased by4.04%

Worsened metrics

Number of low supply chain risk alerts

4

increased by33.33%

Dependency changes

• Updatedjsdoc3@git+https://github.com/jsdoc3/jsdoc.git#cfff8dd035ad376892139192c03718ce2dcc20f0