Merge pull request #204 from brettz9/valid-type-namepaths

feat: check invalid and/or empty namepaths

Author: gajus

README.md

@@ -823,6 +823,13 @@ The following patterns are not considered problems:
  */
 function quux (foo) {
 
+}
+
+/**
+ *
+ */
+function quux (foo) {
+
 }
 ````
 
@@ -874,6 +881,7 @@ license
 listens
 member
 memberof
+memberof!
 mixes
 mixin
 module
@@ -992,6 +1000,13 @@ function quux (foo) {
 
 }
 
+/**
+ * @memberof! foo
+ */
+function quux (foo) {
+
+}
+
 /**
  * @arg foo
  */
@@ -1053,6 +1068,7 @@ function quux (foo) {
  * @listens
  * @member
  * @memberof
+ * @memberof!
  * @mixes
  * @mixin
  * @module
@@ -2694,6 +2710,56 @@ function quux() {
 
 }
 // Message: Syntax error in type: Array<string
+
+/**
+ * @borrows foo% as bar
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: foo%
+
+/**
+ * @borrows foo as bar%
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: bar%
+
+/**
+ * @borrows foo
+ */
+function quux() {
+
+}
+// Message: @borrows must have an "as" expression. Found ""
+
+/**
+ * @see foo%
+ */
+function quux() {
+
+}
+// Settings: {"jsdoc":{"checkSeesForNamepaths":true}}
+// Message: Syntax error in type: foo%
+
+/**
+ * @alias module:abc#event:foo-bar
+ */
+function quux() {
+
+}
+// Message: Syntax error in type: module:abc#event:foo-bar
+
+/**
+ * @callback
+ */
+function quux() {
+
+}
+// Settings: {"jsdoc":{"allowEmptyNamepaths":false}}
+// Message: Syntax error in type: 
 ````
 
 The following patterns are not considered problems:
@@ -2720,6 +2786,34 @@ function quux() {
 
 }
 
+/**
+ * @borrows foo as bar
+ */
+function quux() {
+
+}
+
+/**
+ * @see foo%
+ */
+function quux() {
+
+}
+
+/**
+ * @alias module:svgcanvas.SvgCanvas#event:ext_langReady
+ */
+function quux() {
+
+}
+
+/**
+ * @callback
+ */
+function quux() {
+
+}
+
 /**
  * @see {@link foo}
  */

src/iterateJsdoc.js

@@ -34,11 +34,13 @@ const curryUtils = (
   matchingFileName,
   eslintrcForExamples,
   allowInlineConfig,
+  allowEmptyNamepaths,
   reportUnusedDisableDirectives,
   noDefaultExampleRules,
   allowOverrideWithoutParam,
   allowImplementsWithoutParam,
   allowAugmentsExtendsWithoutParam,
+  checkSeesForNamepaths,
   ancestors,
   sourceCode
 ) => {
@@ -131,6 +133,15 @@ const curryUtils = (
   utils.isAugmentsExtendsAllowedWithoutParam = () => {
     return allowAugmentsExtendsWithoutParam;
   };
+  utils.isNamepathType = (tagName) => {
+    return jsdocUtils.isNamepathType(tagName, checkSeesForNamepaths);
+  };
+  utils.passesEmptyNamepathCheck = (tag) => {
+    return !tag.name && allowEmptyNamepaths && _.includes([
+      // These may serve some minor purpose when empty
+      'callback', 'event', 'listens', 'fires', 'emits'
+    ], tag.tag);
+  };
 
   utils.getClassJsdocNode = () => {
     const greatGrandParent = ancestors.slice(-3)[0];
@@ -179,12 +190,14 @@ export default (iterator) => {
     const configFile = _.get(context, 'settings.jsdoc.configFile');
     const eslintrcForExamples = _.get(context, 'settings.jsdoc.eslintrcForExamples') !== false;
     const allowInlineConfig = _.get(context, 'settings.jsdoc.allowInlineConfig') !== false;
+    const allowEmptyNamepaths = _.get(context, 'settings.jsdoc.allowEmptyNamepaths') !== false;
     const reportUnusedDisableDirectives = _.get(context, 'settings.jsdoc.reportUnusedDisableDirectives') !== false;
     const captionRequired = Boolean(_.get(context, 'settings.jsdoc.captionRequired'));
     const noDefaultExampleRules = Boolean(_.get(context, 'settings.jsdoc.noDefaultExampleRules'));
     const allowOverrideWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowOverrideWithoutParam'));
     const allowImplementsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowImplementsWithoutParam'));
     const allowAugmentsExtendsWithoutParam = Boolean(_.get(context, 'settings.jsdoc.allowAugmentsExtendsWithoutParam'));
+    const checkSeesForNamepaths = Boolean(_.get(context, 'settings.jsdoc.checkSeesForNamepaths'));
 
     const checkJsdoc = (functionNode) => {
       const jsdocNode = sourceCode.getJSDocComment(functionNode);
@@ -245,11 +258,13 @@ export default (iterator) => {
         matchingFileName,
         eslintrcForExamples,
         allowInlineConfig,
+        allowEmptyNamepaths,
         reportUnusedDisableDirectives,
         noDefaultExampleRules,
         allowOverrideWithoutParam,
         allowImplementsWithoutParam,
         allowAugmentsExtendsWithoutParam,
+        checkSeesForNamepaths,
         ancestors,
         sourceCode
       );

src/jsdocUtils.js

@@ -92,12 +92,36 @@ const hasATag = (jsdoc : Object, targetTagNames : Array) : boolean => {
   });
 };
 
+const namepathAsNameTags = [
+  'alias',
+  'augments',
+  'callback',
+  'extends',
+  'lends',
+  'memberof',
+  'memberof!',
+  'mixes',
+  'name',
+  'this',
+
+  'emits',
+  'event',
+  'fires',
+  'listens'
+];
+
+const isNamepathType = (tagName, checkSeesForNamepaths) => {
+  return _.includes(namepathAsNameTags, tagName) ||
+    tagName === 'see' && checkSeesForNamepaths;
+};
+
 export default {
   getFunctionParameterNames,
   getJsdocParameterNames,
   getJsdocParameterNamesDeep,
   getPreferredTagName,
   hasATag,
   hasTag,
+  isNamepathType,
   isValidTag
 };

src/rules/validTypes.js

@@ -7,19 +7,49 @@ const isLink = (tag) => {
   return /^(@link|@linkcode|@linkplain|@tutorial) /.test(tag);
 };
 
+const asExpression = /as\s+/;
+
 export default iterateJsdoc(({
   jsdoc,
-  report
+  report,
+  utils
 }) => {
   _.forEach(jsdoc.tags, (tag) => {
-    if (tag.type && !isLink(tag.type)) {
+    const validTypeParsing = function (type) {
       try {
-        parse(tag.type);
+        parse(type);
       } catch (error) {
         if (error.name === 'SyntaxError') {
-          report('Syntax error in type: ' + tag.type, null, tag);
+          report('Syntax error in type: ' + type, null, tag);
+
+          return false;
         }
       }
+
+      return true;
+    };
+
+    if (tag.tag === 'borrows') {
+      const thisNamepath = tag.description.replace(asExpression, '');
+
+      if (!asExpression.test(tag.description) || !thisNamepath) {
+        report('@borrows must have an "as" expression. Found "' + tag.description + '"', null, tag);
+
+        return;
+      }
+
+      if (validTypeParsing(thisNamepath)) {
+        const thatNamepath = tag.name;
+
+        validTypeParsing(thatNamepath);
+      }
+    } else if (utils.isNamepathType(tag.tag)) {
+      if (utils.passesEmptyNamepathCheck(tag)) {
+        return;
+      }
+      validTypeParsing(tag.name);
+    } else if (tag.type && !isLink(tag.type)) {
+      validTypeParsing(tag.type);
     }
   });
 });