Infer module membership for [module.]exports (fixes #113)

Author: jfirebaugh

lib/infer/membership.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var types = require('ast-types'),
+  pathParse = require('parse-filepath'),
   isJSDocComment = require('../../lib/is_jsdoc_comment'),
   parse = require('../../lib/parse');
 
@@ -56,22 +57,15 @@ function extractIdentifiers(path) {
 }
 
 /**
- * Set `memberof` and `instance`/`static` tags on `comment` based on the
- * array of `identifiers`. If the last element of the `identifiers` is
- * `"prototype"`, it is assumed to be an instance member; otherwise static.
- *
- * @param {Object} comment comment for which to infer memberships
+ * Test whether some identifiers refer to a module export (`exports` or `module.exports`).
  * @param {Array<string>} identifiers array of identifier names
- * @returns {undefined} mutates `comment`
- * @private
+ * @returns {boolean} true if identifiers refer to a module export
  */
-function inferMembershipFromIdentifiers(comment, identifiers) {
-  if (identifiers[identifiers.length - 1] === 'prototype') {
-    comment.memberof = identifiers.slice(0, -1).join('.');
-    comment.scope = 'instance';
-  } else {
-    comment.memberof = identifiers.join('.');
-    comment.scope = 'static';
+function isModuleExport(identifiers) {
+  switch (identifiers.length) {
+  case 1: return identifiers[0] === 'exports';
+  case 2: return identifiers[0] === 'module' && identifiers[1] === 'exports';
+  default: return false;
   }
 }
 
@@ -84,7 +78,41 @@ function inferMembershipFromIdentifiers(comment, identifiers) {
  * @returns {Object} comment with membership inferred
  */
 module.exports = function () {
+  var currentModule;
+
+  function inferModuleName(comment) {
+    return (comment.module && comment.module.name) ||
+      pathParse(comment.context.file).name;
+  }
+
+  /**
+   * Set `memberof` and `instance`/`static` tags on `comment` based on the
+   * array of `identifiers`. If the last element of the `identifiers` is
+   * `"prototype"`, it is assumed to be an instance member; otherwise static.
+   *
+   * @param {Object} comment comment for which to infer memberships
+   * @param {Array<string>} identifiers array of identifier names
+   * @returns {undefined} mutates `comment`
+   * @private
+   */
+  function inferMembershipFromIdentifiers(comment, identifiers) {
+    if (isModuleExport(identifiers)) {
+      comment.memberof = inferModuleName(currentModule || comment);
+      comment.scope = 'static';
+    } else if (identifiers[identifiers.length - 1] === 'prototype') {
+      comment.memberof = identifiers.slice(0, -1).join('.');
+      comment.scope = 'instance';
+    } else {
+      comment.memberof = identifiers.join('.');
+      comment.scope = 'static';
+    }
+  }
+
   return function inferMembership(comment) {
+    if (comment.module) {
+      currentModule = comment;
+    }
+
     if (comment.memberof) {
       return comment;
     }

package.json

@@ -35,6 +35,7 @@
     "mdast-toc": "^1.1.0",
     "micromatch": "^2.1.6",
     "module-deps": "^3.7.3",
+    "parse-filepath": "^0.6.3",
     "remote-origin-url": "^0.4.0",
     "resolve": "^1.1.6",
     "slugg": "^0.1.2",

test/lib/infer/membership.js

@@ -5,15 +5,15 @@ var test = require('tap').test,
   parse = require('../../../lib/parsers/javascript'),
   inferMembership = require('../../../lib/infer/membership')();
 
-function toComment(fn, filename) {
+function toComment(fn, file) {
   return parse({
-    file: filename,
+    file: file,
     source: fn instanceof Function ? '(' + fn.toString() + ')' : fn
   });
 }
 
-function evaluate(fn, callback) {
-  return toComment(fn, callback).map(inferMembership);
+function evaluate(fn, file) {
+  return toComment(fn, file).map(inferMembership);
 }
 
 function Foo() {}
@@ -186,3 +186,70 @@ test('inferMembership', function (t) {
 
   t.end();
 });
+
+test('inferMembership - exports', function (t) {
+  var result = evaluate(function () {
+    /**
+     * @module mod
+     */
+    /** Test */
+    exports.foo = 1;
+  });
+
+  t.equal(result.length, 2);
+  t.equal(result[1].memberof, 'mod');
+  t.end();
+});
+
+test('inferMembership - module.exports', function (t) {
+  var result = evaluate(function () {
+    /**
+     * @module mod
+     */
+    /** Test */
+    module.exports.foo = 1;
+  });
+
+  t.equal(result.length, 2);
+  t.equal(result[1].memberof, 'mod');
+  t.end();
+});
+
+test('inferMembership - not module exports', function (t) {
+  var result = evaluate(function () {
+    /**
+     * @module mod
+     */
+    /** Test */
+    global.module.exports.foo = 1;
+  }, '/path/mod.js');
+
+  t.equal(result.length, 2);
+  t.notEqual(result[0].memberof, 'mod');
+  t.end();
+});
+
+test('inferMembership - anonymous module', function (t) {
+  var result = evaluate(function () {
+    /**
+     * @module
+     */
+    /** Test */
+    exports.foo = 1;
+  }, '/path/mod.js');
+
+  t.equal(result.length, 2);
+  t.equal(result[1].memberof, 'mod');
+  t.end();
+});
+
+test('inferMembership - no module', function (t) {
+  var result = evaluate(function () {
+    /** Test */
+    exports.foo = 1;
+  }, '/path/mod.js');
+
+  t.equal(result.length, 1);
+  t.equal(result[0].memberof, 'mod');
+  t.end();
+});