refactor: easier APIs

Author: brettz9

src/WarnSettings.js

@@ -5,7 +5,7 @@ const WarnSettings = function () {
   return {
     /**
      * Warn only once for each context and setting
-     * @param {import('eslint').Rule.RuleContext} context
+     * @param {{}} context
      * @param {string} setting
      * @returns {boolean}
      */
@@ -16,7 +16,7 @@ const WarnSettings = function () {
     },
 
     /**
-     * @param {import('eslint').Rule.RuleContext} context
+     * @param {{}} context
      * @param {string} setting
      * @returns {void}
      */

src/iterateJsdoc.js

@@ -629,10 +629,10 @@ const getBasicUtils = (context, {
     tagName,
   }) => {
     const ret = jsdocUtils.getPreferredTagNameSimple(
-      context,
-      /** @type {import('./jsdocUtils.js').ParserMode} */ (mode),
       tagName,
+      /** @type {import('./jsdocUtils.js').ParserMode} */ (mode),
       tagNamePreference,
+      context,
     );
     const isObject = ret && typeof ret === 'object';
     if (ret === false || (isObject && !ret.replacement)) {
@@ -1340,8 +1340,10 @@ const getUtils = (
   /** @type {GetPreferredTagName} */
   utils.getPreferredTagName = (args) => {
     return jsdocUtils.getPreferredTagName(
-      context, mode, report, tagNamePreference,
-      jsdoc, args
+      jsdoc, {
+        ...args,
+        context, mode, report, tagNamePreference,
+      }
     );
   };
 
@@ -1644,8 +1646,10 @@ const getUtils = (
   /** @type {ForEachPreferredTag} */
   utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
     return jsdocUtils.forEachPreferredTag(
-      context, mode, report, tagNamePreference,
-      jsdoc, tagName, arrayHandler, skipReportingBlockedTag
+      jsdoc, tagName, arrayHandler, {
+        skipReportingBlockedTag,
+        context, mode, report, tagNamePreference
+      }
     );
   };
 

src/jsdocUtils.js

@@ -521,7 +521,7 @@ const modeWarnSettings = WarnSettings();
 
 /**
  * @param {ParserMode|undefined} mode
- * @param {import('eslint').Rule.RuleContext} context
+ * @param {Reporter} context
  * @returns {import('./tagNames.js').AliasedTags}
  */
 const getTagNamesForMode = (mode, context) => {
@@ -602,20 +602,30 @@ const getTagDescription = (tg, returnArray) => {
 };
 
 /**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode|undefined} mode
+ * @typedef {{
+ *   report: (descriptor: import('eslint').Rule.ReportDescriptor) => void
+ * }} Reporter
+ */
+
+/**
  * @param {string} name
+ * @param {ParserMode|undefined} mode
  * @param {TagNamePreference} tagPreference
+ * @param {Reporter} context
  * @returns {string|false|{
  *   message: string;
  *   replacement?: string|undefined;
  * }}
  */
 const getPreferredTagNameSimple = (
-  context,
-  mode,
   name,
+  mode,
   tagPreference = {},
+  context = {
+    report () {
+      // No-op
+    }
+  },
 ) => {
   const prefValues = Object.values(tagPreference);
   if (prefValues.includes(name) || prefValues.some((prefVal) => {
@@ -718,16 +728,16 @@ const getTags = (jsdoc, tagName) => {
 };
 
 /**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode} mode
- * @param {import('./iterateJsdoc.js').Report} report
- * @param {TagNamePreference} tagNamePreference
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {{
  *   tagName: string,
+ *   context: import('eslint').Rule.RuleContext,
+ *   mode: ParserMode,
+ *   report: import('./iterateJsdoc.js').Report
+ *   tagNamePreference: TagNamePreference
  *   skipReportingBlockedTag?: boolean,
  *   allowObjectReturn?: boolean,
- *   defaultMessage?: string
+ *   defaultMessage?: string,
  * }} cfg
  * @returns {string|undefined|false|{
  *   message: string;
@@ -737,13 +747,14 @@ const getTags = (jsdoc, tagName) => {
  *   tagName: string
  * }}
  */
-const getPreferredTagName = (context, mode, report, tagNamePreference, jsdoc, {
+const getPreferredTagName = (jsdoc, {
   tagName,
+  context, mode, report, tagNamePreference,
   skipReportingBlockedTag = false,
   allowObjectReturn = false,
   defaultMessage = `Unexpected tag \`@${tagName}\``,
 }) => {
-  const ret = getPreferredTagNameSimple(context, mode, tagName, tagNamePreference);
+  const ret = getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
   const isObject = ret && typeof ret === 'object';
   if (hasTag(jsdoc, tagName) && (ret === false || isObject && !ret.replacement)) {
     if (skipReportingBlockedTag) {
@@ -763,24 +774,33 @@ const getPreferredTagName = (context, mode, report, tagNamePreference, jsdoc, {
 };
 
 /**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode} mode
- * @param {import('./iterateJsdoc.js').Report} report
- * @param {TagNamePreference} tagNamePreference
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string} tagName
  * @param {(
-*   matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
-*   targetTagName: string
-* ) => void} arrayHandler
-* @param {boolean} [skipReportingBlockedTag]
-* @returns {void}
-*/
-const forEachPreferredTag = (context, mode, report, tagNamePreference, jsdoc, tagName, arrayHandler, skipReportingBlockedTag = false) => {
+ *   matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
+ *   targetTagName: string
+ * ) => void} arrayHandler
+ * @param {object} cfg
+ * @param {import('eslint').Rule.RuleContext} cfg.context
+ * @param {ParserMode} cfg.mode
+ * @param {import('./iterateJsdoc.js').Report} cfg.report
+ * @param {TagNamePreference} cfg.tagNamePreference
+ * @param {boolean} [cfg.skipReportingBlockedTag]
+ * @returns {void}
+ */
+const forEachPreferredTag = (
+  jsdoc, tagName, arrayHandler,
+  {
+    context, mode, report,
+    tagNamePreference,
+    skipReportingBlockedTag = false,
+  }
+) => {
   const targetTagName = /** @type {string|false} */ (
-    getPreferredTagName(context, mode, report, tagNamePreference, jsdoc, {
+    getPreferredTagName(jsdoc, {
       skipReportingBlockedTag,
       tagName,
+      context, mode, report, tagNamePreference
     })
   );
   if (!targetTagName ||

test/jsdocUtils.js

@@ -12,24 +12,32 @@ describe('jsdocUtils', () => {
     context('no preferences', () => {
       context('alias name', () => {
         it('returns the primary tag name', () => {
-          expect(jsdocUtils.getPreferredTagNameSimple(/** @type {BadArgument} */ ({}), 'jsdoc', 'return')).to.equal('returns');
+          expect(jsdocUtils.getPreferredTagNameSimple(
+            'return', 'jsdoc',
+          )).to.equal('returns');
         });
         it('works with the constructor tag', () => {
-          expect(jsdocUtils.getPreferredTagNameSimple(/** @type {BadArgument} */ ({}), 'jsdoc', 'constructor')).to.equal('class');
+          expect(jsdocUtils.getPreferredTagNameSimple('constructor', 'jsdoc')).to.equal('class');
         });
       });
       it('works with tags that clash with prototype properties', () => {
-        expect(jsdocUtils.getPreferredTagNameSimple(/** @type {BadArgument} */ ({}), 'jsdoc', 'toString')).to.equal('toString');
+        expect(jsdocUtils.getPreferredTagNameSimple('toString', 'jsdoc')).to.equal('toString');
       });
       it('returns the primary tag name', () => {
-        expect(jsdocUtils.getPreferredTagNameSimple(/** @type {BadArgument} */ ({}), 'jsdoc', 'returns')).to.equal('returns');
+        expect(jsdocUtils.getPreferredTagNameSimple('returns', 'jsdoc')).to.equal('returns');
       });
     });
     context('with preferences', () => {
       it('returns the preferred tag name', () => {
-        expect(jsdocUtils.getPreferredTagNameSimple(/** @type {BadArgument} */ ({}), 'jsdoc', 'return', /** @type {BadArgument} */ ({
+        expect(jsdocUtils.getPreferredTagNameSimple('return', 'jsdoc', {
           returns: 'return',
-        }))).to.equal('return');
+        })).to.equal('return');
+      });
+    });
+
+    context('with context', () => {
+      it('returns the preferred tag name', () => {
+        expect(jsdocUtils.getPreferredTagNameSimple('returns', /** @type {BadArgument} */ ('badArg'))).to.equal('returns');
       });
     });
   });