jsdoc-api - npm Package Compare versions

Comparing version 0.3.0 to 0.4.0

es5/explain-stream.js

@@ -14,2 +14,3 @@ 'use strict';
 var arrayify = require('array-back');
+var jsdoc = require('./jsdoc');
 
@@ -45,3 +46,4 @@ var ExplainStream = (function (_Duplex) {
 
-      this.explain(this.options).then(function (output) {
+      var explain = new jsdoc.Explain(this.options);
+      explain.execute().then(function (output) {
         _this2.push(JSON.stringify(output, null, '  '));
@@ -48,0 +50,0 @@ _this2.push(null);

es5/jsdoc-api.js

@@ -7,9 +7,7 @@ 'use strict';
 var spawnSync = require('child_process').spawnSync;
-var spawn = require('child_process').spawn;
 var toSpawnArgs = require('object-to-spawn-args');
 var arrayify = require('array-back');
-var collectJson = require('collect-json');
-var collectAll = require('collect-all');
 var ExplainStream = require('./explain-stream');
 var TempFile = require('./temp-file');
+var jsdoc = require('./jsdoc');
 
@@ -24,69 +22,9 @@ exports.explainSync = explainSync;
 function explainSync(options) {
-  options = Object.assign({}, options);
-  options.files = arrayify(options.files);
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source');
-
-  var tempFile = null;
-  if (options.source) tempFile = new TempFile(options.source);
-
-  var jsdocOptions = Object.assign({}, options);
-  delete jsdocOptions.files;
-  delete jsdocOptions.source;
-
-  var jsdocArgs = toSpawnArgs(jsdocOptions).concat(['-X']).concat(options.source ? tempFile.path : options.files);
-
-  var result = spawnSync(jsdocPath, jsdocArgs);
-  if (tempFile) tempFile.delete();
-  return JSON.parse(result.stdout);
+  var jsdocExplainSync = new jsdoc.ExplainSync(options);
+  return jsdocExplainSync.execute();
 }
 
 function explain(options) {
-  options = Object.assign({ files: [] }, options);
-  options.files = arrayify(options.files);
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source');
-
-  var tempFile = null;
-  if (options.source) tempFile = new TempFile(options.source);
-
-  var jsdocOptions = Object.assign({}, options);
-  delete jsdocOptions.files;
-  delete jsdocOptions.source;
-
-  var jsdocArgs = toSpawnArgs(jsdocOptions).concat(['-X']).concat(options.source ? tempFile.path : options.files);
-
-  var jsdocOutput = {
-    stdout: '',
-    stderr: '',
-    collectInto: function collectInto(dest) {
-      var _this = this;
-
-      return collectAll(function (data) {
-        return _this[dest] = data.toString();
-      });
-    }
-  };
-
-  return new Promise(function (resolve, reject) {
-    var handle = spawn(jsdocPath, jsdocArgs);
-    handle.stderr.pipe(jsdocOutput.collectInto('stderr'));
-    handle.stdout.pipe(jsdocOutput.collectInto('stdout'));
-
-    handle.on('close', function (code) {
-
-      if (code) {
-        var err = new Error(jsdocOutput.stderr.trim());
-        err.name = 'INVALID_FILES';
-        reject(err);
-      } else {
-        if (code === 0 && /There are no input files to process/.test(jsdocOutput.stdout)) {
-          var err = new Error('There are no input files to process');
-          err.name = 'INVALID_FILES';
-          reject(err);
-        } else {
-          resolve(JSON.parse(jsdocOutput.stdout));
-        }
-      }
-      if (tempFile) tempFile.delete();
-    });
-  });
+  var jsdocExplain = new jsdoc.Explain(options);
+  return jsdocExplain.execute();
 }
@@ -99,16 +37,4 @@
 function renderSync(options) {
-  options = Object.assign({ files: [] }, options);
-  options.files = arrayify(options.files);
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source');
-
-  var tempFile = null;
-  if (options.source) tempFile = new TempFile(options.source);
-
-  var jsdocOptions = Object.assign({}, options);
-  delete jsdocOptions.files;
-  delete jsdocOptions.source;
-
-  var jsdocArgs = toSpawnArgs(jsdocOptions).concat(options.source ? tempFile.path : options.files);
-
-  spawnSync(jsdocPath, jsdocArgs);
+  var render = new jsdoc.RenderSync(options);
+  return render.execute();
 }

lib/explain-stream.js

@@ -5,2 +5,3 @@ 'use strict'
 const arrayify = require('array-back')
+const jsdoc = require('./jsdoc')
 
@@ -26,3 +27,4 @@ class ExplainStream extends Duplex {
   start () {
-    this.explain(this.options)
+    const explain = new jsdoc.Explain(this.options)
+    explain.execute()
       .then(output => {
@@ -29,0 +31,0 @@ this.push(JSON.stringify(output, null, '  '))

lib/jsdoc-api.js

@@ -6,9 +6,7 @@ 'use strict'
 const spawnSync = require('child_process').spawnSync
-const spawn = require('child_process').spawn
 const toSpawnArgs = require('object-to-spawn-args')
 const arrayify = require('array-back')
-const collectJson = require('collect-json')
-const collectAll = require('collect-all')
 const ExplainStream = require('./explain-stream')
 const TempFile = require('./temp-file')
+const jsdoc = require('./jsdoc')
 
@@ -38,23 +36,7 @@ /**
  * @static
- * @node Requires version 0.12 and above
+ * @prerequisite Requires node v0.12 or above
  */
 function explainSync (options) {
-  options = Object.assign({}, options)
-  options.files = arrayify(options.files)
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source')
-
-  let tempFile = null
-  if (options.source) tempFile = new TempFile(options.source)
-
-  const jsdocOptions = Object.assign({}, options)
-  delete jsdocOptions.files
-  delete jsdocOptions.source
-
-  const jsdocArgs = toSpawnArgs(jsdocOptions)
-    .concat([ '-X' ])
-    .concat(options.source ? tempFile.path : options.files)
-
-  const result = spawnSync(jsdocPath, jsdocArgs)
-  if (tempFile) tempFile.delete()
-  return JSON.parse(result.stdout)
+  const jsdocExplainSync = new jsdoc.ExplainSync(options)
+  return jsdocExplainSync.execute()
 }
@@ -70,53 +52,6 @@
  * @static
- * @throws `INVALID_FILES` - One or more files was not valid source code
  */
 function explain (options) {
-  options = Object.assign({ files: [] }, options)
-  options.files = arrayify(options.files)
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source')
-
-  let tempFile = null
-  if (options.source) tempFile = new TempFile(options.source)
-
-  const jsdocOptions = Object.assign({}, options)
-  delete jsdocOptions.files
-  delete jsdocOptions.source
-
-  const jsdocArgs = toSpawnArgs(jsdocOptions)
-    .concat([ '-X' ])
-    .concat(options.source ? tempFile.path : options.files)
-
-  const jsdocOutput = {
-    stdout: '',
-    stderr: '',
-    collectInto (dest) {
-      return collectAll(data => this[dest] = data.toString())
-    }
-  }
-
-  return new Promise((resolve, reject) => {
-    const handle = spawn(jsdocPath, jsdocArgs)
-    handle.stderr.pipe(jsdocOutput.collectInto('stderr'))
-    handle.stdout.pipe(jsdocOutput.collectInto('stdout'))
-
-    handle
-      .on('close', code => {
-        // console.error('CLOSE YEAH?', code, jsdocOutput);
-
-        if (code) {
-          const err = new Error(jsdocOutput.stderr.trim())
-          err.name = 'INVALID_FILES'
-          reject(err)
-        } else {
-          if (code === 0 && /There are no input files to process/.test(jsdocOutput.stdout)) {
-            const err = new Error('There are no input files to process')
-            err.name = 'INVALID_FILES'
-            reject(err)
-          } else {
-            resolve(JSON.parse(jsdocOutput.stdout))
-          }
-        }
-        if (tempFile) tempFile.delete()
-      })
-  })
+  const jsdocExplain = new jsdoc.Explain(options)
+  return jsdocExplain.execute()
 }
@@ -141,20 +76,8 @@
  * @param [options.destination] - destination path
+ * @prerequisite Requires node v0.12 or above
  * @static
  */
 function renderSync (options) {
-  options = Object.assign({ files: [] }, options)
-  options.files = arrayify(options.files)
-  assert.ok(options.files.length || options.source, 'Must set either .files or .source')
-
-  let tempFile = null
-  if (options.source) tempFile = new TempFile(options.source)
-
-  const jsdocOptions = Object.assign({}, options)
-  delete jsdocOptions.files
-  delete jsdocOptions.source
-
-  const jsdocArgs = toSpawnArgs(jsdocOptions)
-    .concat(options.source ? tempFile.path : options.files)
-
-  spawnSync(jsdocPath, jsdocArgs)
+  const render = new jsdoc.RenderSync(options)
+  return render.execute()
 }

package.json

 {
   "name": "jsdoc-api",
   "author": "Lloyd Brookes <[e-mail]>",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A programmatic interface for jsdoc",
@@ -41,4 +41,6 @@ "repository": "https://github.com/75lb/jsdoc-api.git",
     "feature-detect-es6": "^1.2.0",
+    "file-set": "^0.2.8",
     "jsdoc-75lb": "^3.5",
     "object-to-spawn-args": "^1",
+    "promise.prototype.finally": "^1.0.1",
     "temp-path": "^1.0.0",
@@ -45,0 +47,0 @@ "walk-back": "^1.0.1"

README.md

@@ -27,3 +27,3 @@ [![view on npm](http://img.shields.io/npm/v/jsdoc-api.svg)](https://www.npmjs.org/package/jsdoc-api)
 **Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
-**Node**: Requires version 0.12 and above  
+**Prerequisite**: Requires node v0.12 or above  
 
@@ -39,6 +39,2 @@ | Param | Type |
 **Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
-**Throws**:
-
-- `INVALID_FILES` - One or more files was not valid source code
-
 **Fulfil**: <code>object[]</code> - jsdoc explain output  
@@ -67,2 +63,3 @@
 **Kind**: static method of <code>[jsdoc-api](#module_jsdoc-api)</code>  
+**Prerequisite**: Requires node v0.12 or above  
 
@@ -77,4 +74,5 @@ | Param | Type | Description |
 
+
 * * *
 
 &copy; 2015 Lloyd Brookes \<[e-mail]\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).

test/createExplainStream.js

@@ -5,2 +5,3 @@ var test = require('tape')
 var collectJson = require('collect-json')
+var path = require('path')
 
@@ -42,3 +43,3 @@ test('.createExplainStream({ files })', function (t) {
     .on('error', function (err) {
-      t.strictEqual(err.name, 'INVALID_FILES')
+      t.strictEqual(err.name, 'JSDOC_ERROR')
     })
@@ -49,1 +50,24 @@ .pipe(collectJson(function (output) {
 })
+
+test('.createExplainStream: missing files', function (t) {
+  t.plan(1)
+  jsdoc.createExplainStream({ files: 'asljkdhfkljads' })
+    .on('error', function (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    })
+    .pipe(collectJson(function (output) {
+      t.fail('should not reach here')
+    }))
+})
+
+test('.createExplainStream: invalid doclet syntax', function (t) {
+  t.plan(1)
+  var input = path.resolve(__dirname, '..', 'node_modules', 'jsdoc2md-testbed', 'build', 'input/buggy/bad-syntax.js')
+  jsdoc.createExplainStream({ files: input })
+    .on('error', function (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    })
+    .pipe(collectJson(function (output) {
+      t.fail('should not reach here')
+    }))
+})

test/explain-sync.js

@@ -5,2 +5,3 @@ var test = require('tape')
 var spawnSync = require('child_process').spawnSync
+var path = require('path')
 
@@ -28,2 +29,33 @@ /* only test on a node version with spawnSync */
   })
+
+  test('.explainSync: no valid files', function (t) {
+    t.plan(1)
+    var output
+    try {
+      output = jsdoc.explainSync({ files: 'package.json' })
+    } catch (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    }
+  })
+
+  test('.explainSync: missing files', function (t) {
+    t.plan(1)
+    var output
+    try {
+      output = jsdoc.explainSync({ files: 'oyutigbl' })
+    } catch (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    }
+  })
+
+  test('.explainSync: invalid doclet syntax', function (t) {
+    t.plan(1)
+    var output
+    try {
+      var input = path.resolve(__dirname, '..', 'node_modules', 'jsdoc2md-testbed', 'build', 'input/buggy/bad-syntax.js')
+      output = jsdoc.explainSync({ files: input })
+    } catch (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    }
+  })
 }

test/explain.js

 var test = require('tape')
 var jsdoc = require('../')
 var Fixture = require('./lib/fixture')
+var path = require('path')
 
-process.on('unhandledRejection', function (err) {
-  console.error(err.stack);
-})
-
 test('.explain({ files })', function (t) {
@@ -27,3 +24,3 @@ t.plan(1)
 
-test("file doesn't exist", function (t) {
+test(".explain: file doesn't exist", function (t) {
   t.plan(1)
@@ -35,4 +32,16 @@ jsdoc.explain({ files: 'sdfafafirifrj' })
     .catch(function (err) {
-      t.strictEqual(err.name, 'INVALID_FILES')
+      t.strictEqual(err.name, 'JSDOC_ERROR')
     })
 })
+
+test('.explain: invalid doclet syntax', function (t) {
+  t.plan(1)
+  var input = path.resolve(__dirname, '..', 'node_modules', 'jsdoc2md-testbed', 'build', 'input/buggy/bad-syntax.js')
+  jsdoc.explain({ files: input })
+    .then(function () {
+      t.fail('should not reach here')
+    })
+    .catch(function (err) {
+      t.strictEqual(err.name, 'JSDOC_ERROR')
+    })
+})

test/lib/fixture.js

@@ -9,3 +9,3 @@ var path = require('path')
 function Fixture (name) {
-  this.folder = path.resolve(__dirname, '..', '..', 'node_modules', 'jsdoc2md-testbed', name)
+  this.folder = path.resolve(__dirname, '..', '..', 'node_modules', 'jsdoc2md-testbed', 'build', name)
   this.sourcePath = path.resolve(this.folder, '0-src.js')
@@ -12,0 +12,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1060156

increased by0.81%

Number of package files

48

increased by4.35%

Lines of code

1383

increased by24.37%

Worsened metrics

Dependency count

12

increased by20%

Number of lines in readme file

75

decreased by-2.6%

Number of medium supply chain risk alerts

8

increased by33.33%

Dependency changes

• + Addedfile-set@^0.2.8

• + Addedpromise.prototype.finally@^1.0.1

• + Addedarray-tools@2.0.9(transitive)

• + Addedbalanced-match@1.0.2(transitive)

• + Addedbrace-expansion@1.1.11(transitive)

• + Addedconcat-map@0.0.1(transitive)

• + Addedfile-set@0.2.8(transitive)

• + Addedfilter-where@1.0.1(transitive)

• + Addedglob@4.5.3(transitive)

• + Addedinflight@1.0.6(transitive)

• + Addedinherits@2.0.4(transitive)

• + Addedminimatch@2.0.10(transitive)

• + Addedonce@1.4.0(transitive)

• + Addedpromise.prototype.finally@1.0.1(transitive)

• + Addedreduce-extract@1.0.0(transitive)

• + Addedreduce-flatten@1.0.1(transitive)

• + Addedreduce-unique@1.0.0(transitive)

• + Addedreduce-without@1.0.1(transitive)

• + Addedsort-array@1.1.2(transitive)

• + Addedwrappy@1.0.2(transitive)