diff --git a/src/WarnSettings.js b/src/WarnSettings.js index aee7c92b..37618911 100644 --- a/src/WarnSettings.js +++ b/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} */ diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js index 75df9b27..b5f93a3c 100644 --- a/src/iterateJsdoc.js +++ b/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 + } ); }; diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js index 59ebe6a9..2afcfc4c 100644 --- a/src/jsdocUtils.js +++ b/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 || diff --git a/test/jsdocUtils.js b/test/jsdocUtils.js index 9152ac9e..b7bd33a2 100644 --- a/test/jsdocUtils.js +++ b/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'); }); }); });