eslint-plugin-jsdoc 56.0.0 → 56.0.2

package/dist/cjs/rules/checkPropertyNames.js

@@ -1,105 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
-/**
- * @param {string} targetTagName
- * @param {boolean} enableFixer
- * @param {import('comment-parser').Block} jsdoc
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @returns {boolean}
- */
-const validatePropertyNames = (targetTagName, enableFixer, jsdoc, utils) => {
-    const propertyTags = Object.entries(jsdoc.tags).filter(([, tag,]) => {
-        return tag.tag === targetTagName;
-    });
-    return propertyTags.some(([, tag,], index) => {
-        /** @type {import('../iterateJsdoc.js').Integer} */
-        let tagsIndex;
-        const dupeTagInfo = propertyTags.find(([tgsIndex, tg,], idx) => {
-            tagsIndex = Number(tgsIndex);
-            return tg.name === tag.name && idx !== index;
-        });
-        if (dupeTagInfo) {
-            utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
-                utils.removeTag(tagsIndex);
-            } : null);
-            return true;
-        }
-        return false;
-    });
-};
-/**
- * @param {string} targetTagName
- * @param {{
- *   idx: number;
- *   name: string;
- *   type: string;
- * }[]} jsdocPropertyNames
- * @param {import('comment-parser').Block} jsdoc
- * @param {Function} report
- */
-const validatePropertyNamesDeep = (targetTagName, jsdocPropertyNames, jsdoc, report) => {
-    /** @type {string} */
-    let lastRealProperty;
-    return jsdocPropertyNames.some(({ idx, name: jsdocPropertyName, }) => {
-        const isPropertyPath = jsdocPropertyName.includes('.');
-        if (isPropertyPath) {
-            if (!lastRealProperty) {
-                report(`@${targetTagName} path declaration ("${jsdocPropertyName}") appears before any real property.`, null, jsdoc.tags[idx]);
-                return true;
-            }
-            let pathRootNodeName = jsdocPropertyName.slice(0, jsdocPropertyName.indexOf('.'));
-            if (pathRootNodeName.endsWith('[]')) {
-                pathRootNodeName = pathRootNodeName.slice(0, -2);
-            }
-            if (pathRootNodeName !== lastRealProperty) {
-                report(`@${targetTagName} path declaration ("${jsdocPropertyName}") root node name ("${pathRootNodeName}") ` +
-                    `does not match previous real property name ("${lastRealProperty}").`, null, jsdoc.tags[idx]);
-                return true;
-            }
-        }
-        else {
-            lastRealProperty = jsdocPropertyName;
-        }
-        return false;
-    });
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, utils, }) => {
-    const { enableFixer = false, } = context.options[0] || {};
-    const jsdocPropertyNamesDeep = utils.getJsdocTagsDeep('property');
-    if (!jsdocPropertyNamesDeep || !jsdocPropertyNamesDeep.length) {
-        return;
-    }
-    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
-        tagName: 'property',
-    }));
-    const isError = validatePropertyNames(targetTagName, enableFixer, jsdoc, utils);
-    if (isError) {
-        return;
-    }
-    validatePropertyNamesDeep(targetTagName, jsdocPropertyNamesDeep, jsdoc, report);
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-property-names.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    enableFixer: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/checkSyntax.js

@@ -1,27 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
-exports.default = (0, iterateJsdoc_js_1.default)(({ jsdoc, report, settings, }) => {
-    const { mode, } = settings;
-    // Don't check for "permissive" and "closure"
-    if (mode === 'jsdoc' || mode === 'typescript') {
-        for (const tag of jsdoc.tags) {
-            if (tag.type.slice(-1) === '=') {
-                report('Syntax should not be Google Closure Compiler style.', null, tag);
-                break;
-            }
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode).',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-syntax.md#repos-sticky-header',
-        },
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/checkTagNames.js

@@ -1,252 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
-const escape_string_regexp_1 = __importDefault(require("escape-string-regexp"));
-// https://babeljs.io/docs/en/babel-plugin-transform-react-jsx/
-const jsxTagNames = new Set([
-    'jsx',
-    'jsxFrag',
-    'jsxImportSource',
-    'jsxRuntime',
-]);
-const typedTagsAlwaysUnnecessary = new Set([
-    'augments',
-    'callback',
-    'class',
-    'enum',
-    'implements',
-    'private',
-    'property',
-    'protected',
-    'public',
-    'readonly',
-    'this',
-    'type',
-    'typedef',
-]);
-const typedTagsNeedingName = new Set([
-    'template',
-]);
-const typedTagsUnnecessaryOutsideDeclare = new Set([
-    'abstract',
-    'access',
-    'class',
-    'constant',
-    'constructs',
-    'default',
-    'enum',
-    'export',
-    'exports',
-    'function',
-    'global',
-    'inherits',
-    'instance',
-    'interface',
-    'member',
-    'memberof',
-    'memberOf',
-    'method',
-    'mixes',
-    'mixin',
-    'module',
-    'name',
-    'namespace',
-    'override',
-    'property',
-    'requires',
-    'static',
-    'this',
-]);
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, jsdocNode, node, report, settings, sourceCode, utils, }) => {
-    const 
-    /**
-     * @type {{
-     *   definedTags: string[],
-     *   enableFixer: boolean,
-     *   jsxTags: boolean,
-     *   typed: boolean
-     }} */ { definedTags = [], enableFixer = true, jsxTags, typed, } = context.options[0] || {};
-    /** @type {(string|undefined)[]} */
-    let definedPreferredTags = [];
-    const { structuredTags, tagNamePreference, } = settings;
-    const definedStructuredTags = Object.keys(structuredTags);
-    const definedNonPreferredTags = Object.keys(tagNamePreference);
-    if (definedNonPreferredTags.length) {
-        definedPreferredTags = Object.values(tagNamePreference).map((preferredTag) => {
-            if (typeof preferredTag === 'string') {
-                // May become an empty string but will be filtered out below
-                return preferredTag;
-            }
-            if (!preferredTag) {
-                return undefined;
-            }
-            if (typeof preferredTag !== 'object') {
-                utils.reportSettings('Invalid `settings.jsdoc.tagNamePreference`. Values must be falsy, a string, or an object.');
-            }
-            return preferredTag.replacement;
-        })
-            .filter(Boolean);
-    }
-    /**
-     * @param {import('eslint').Rule.Node} subNode
-     * @returns {boolean}
-     */
-    const isInAmbientContext = (subNode) => {
-        return subNode.type === 'Program' ?
-            context.getFilename().endsWith('.d.ts') :
-            Boolean(
-            /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (subNode).declare) || isInAmbientContext(subNode.parent);
-    };
-    /**
-     * @param {import('comment-parser').Spec} jsdocTag
-     * @returns {boolean}
-     */
-    const tagIsRedundantWhenTyped = (jsdocTag) => {
-        if (!typedTagsUnnecessaryOutsideDeclare.has(jsdocTag.tag)) {
-            return false;
-        }
-        if (jsdocTag.tag === 'default') {
-            return false;
-        }
-        if (node === null) {
-            return false;
-        }
-        if (context.getFilename().endsWith('.d.ts') && [
-            null, 'Program', undefined,
-        ].includes(node?.parent?.type)) {
-            return false;
-        }
-        if (isInAmbientContext(/** @type {import('eslint').Rule.Node} */ (node))) {
-            return false;
-        }
-        return true;
-    };
-    /**
-     * @param {string} message
-     * @param {import('comment-parser').Spec} jsdocTag
-     * @param {import('../iterateJsdoc.js').Integer} tagIndex
-     * @param {Partial<import('comment-parser').Tokens>} [additionalTagChanges]
-     * @returns {void}
-     */
-    const reportWithTagRemovalFixer = (message, jsdocTag, tagIndex, additionalTagChanges) => {
-        utils.reportJSDoc(message, jsdocTag, enableFixer ? () => {
-            if (jsdocTag.description.trim()) {
-                utils.changeTag(jsdocTag, {
-                    postType: '',
-                    type: '',
-                    ...additionalTagChanges,
-                });
-            }
-            else {
-                utils.removeTag(tagIndex, {
-                    removeEmptyBlock: true,
-                });
-            }
-        } : null, true);
-    };
-    /**
-     * @param {import('comment-parser').Spec} jsdocTag
-     * @param {import('../iterateJsdoc.js').Integer} tagIndex
-     * @returns {boolean}
-     */
-    const checkTagForTypedValidity = (jsdocTag, tagIndex) => {
-        if (typedTagsAlwaysUnnecessary.has(jsdocTag.tag)) {
-            reportWithTagRemovalFixer(`'@${jsdocTag.tag}' is redundant when using a type system.`, jsdocTag, tagIndex, {
-                postTag: '',
-                tag: '',
-            });
-            return true;
-        }
-        if (tagIsRedundantWhenTyped(jsdocTag)) {
-            reportWithTagRemovalFixer(`'@${jsdocTag.tag}' is redundant outside of ambient (\`declare\`/\`.d.ts\`) contexts when using a type system.`, jsdocTag, tagIndex);
-            return true;
-        }
-        if (typedTagsNeedingName.has(jsdocTag.tag) && !jsdocTag.name) {
-            reportWithTagRemovalFixer(`'@${jsdocTag.tag}' without a name is redundant when using a type system.`, jsdocTag, tagIndex);
-            return true;
-        }
-        return false;
-    };
-    for (let tagIndex = 0; tagIndex < jsdoc.tags.length; tagIndex += 1) {
-        const jsdocTag = jsdoc.tags[tagIndex];
-        const tagName = jsdocTag.tag;
-        if (jsxTags && jsxTagNames.has(tagName)) {
-            continue;
-        }
-        if (typed && checkTagForTypedValidity(jsdocTag, tagIndex)) {
-            continue;
-        }
-        const validTags = [
-            ...definedTags,
-            ...( /** @type {string[]} */(definedPreferredTags)),
-            ...definedNonPreferredTags,
-            ...definedStructuredTags,
-            ...typed ? typedTagsNeedingName : [],
-        ];
-        if (utils.isValidTag(tagName, validTags)) {
-            let preferredTagName = utils.getPreferredTagName({
-                allowObjectReturn: true,
-                defaultMessage: `Blacklisted tag found (\`@${tagName}\`)`,
-                tagName,
-            });
-            if (!preferredTagName) {
-                continue;
-            }
-            let message;
-            if (typeof preferredTagName === 'object') {
-                ({
-                    message,
-                    replacement: preferredTagName,
-                } = /** @type {{message: string; replacement?: string | undefined;}} */ (preferredTagName));
-            }
-            if (!message) {
-                message = `Invalid JSDoc tag (preference). Replace "${tagName}" JSDoc tag with "${preferredTagName}".`;
-            }
-            if (preferredTagName !== tagName) {
-                report(message, (fixer) => {
-                    const replacement = sourceCode.getText(jsdocNode).replace(new RegExp(`@${(0, escape_string_regexp_1.default)(tagName)}\\b`, 'v'), `@${preferredTagName}`);
-                    return fixer.replaceText(jsdocNode, replacement);
-                }, jsdocTag);
-            }
-        }
-        else {
-            report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Reports invalid block tag names.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    definedTags: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    enableFixer: {
-                        type: 'boolean',
-                    },
-                    jsxTags: {
-                        type: 'boolean',
-                    },
-                    typed: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/checkTemplateNames.js

@@ -1,189 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importStar(require("../iterateJsdoc.js"));
-const jsdocUtils_js_1 = require("../jsdocUtils.js");
-const jsdoccomment_1 = require("@es-joy/jsdoccomment");
-exports.default = (0, iterateJsdoc_js_1.default)(({ jsdoc, node, report, settings, sourceCode, utils, }) => {
-    const { mode, } = settings;
-    const templateTags = utils.getTags('template');
-    const usedNames = new Set();
-    /**
-     * @param {string} potentialType
-     */
-    const checkForUsedTypes = (potentialType) => {
-        let parsedType;
-        try {
-            parsedType = mode === 'permissive' ?
-                (0, jsdoccomment_1.tryParse)(/** @type {string} */ (potentialType)) :
-                (0, jsdoccomment_1.parse)(/** @type {string} */ (potentialType), mode);
-        }
-        catch {
-            return;
-        }
-        (0, jsdoccomment_1.traverse)(parsedType, (nde) => {
-            const { type, value, } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
-            if (type === 'JsdocTypeName') {
-                usedNames.add(value);
-            }
-        });
-    };
-    const checkParamsAndReturnsTags = (jsdc = jsdoc) => {
-        const paramName = /** @type {string} */ (utils.getPreferredTagName({
-            tagName: 'param',
-        }));
-        const paramTags = (0, jsdocUtils_js_1.getTags)(jsdc, paramName);
-        for (const paramTag of paramTags) {
-            checkForUsedTypes(paramTag.type);
-        }
-        const returnsName = /** @type {string} */ (utils.getPreferredTagName({
-            tagName: 'returns',
-        }));
-        const returnsTags = (0, jsdocUtils_js_1.getTags)(jsdc, returnsName);
-        for (const returnsTag of returnsTags) {
-            checkForUsedTypes(returnsTag.type);
-        }
-    };
-    const checkTemplateTags = () => {
-        for (const tag of templateTags) {
-            const names = utils.parseClosureTemplateTag(tag);
-            for (const nme of names) {
-                if (!usedNames.has(nme)) {
-                    report(`@template ${nme} not in use`, null, tag);
-                }
-            }
-        }
-    };
-    /**
-     * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
-     * @param {boolean} [checkParamsAndReturns]
-     */
-    const checkParameters = (aliasDeclaration, checkParamsAndReturns) => {
-        /* c8 ignore next -- Guard */
-        const { params, } = aliasDeclaration.typeParameters ?? {
-            params: [],
-        };
-        for (const { name: { name, }, } of params) {
-            usedNames.add(name);
-        }
-        if (checkParamsAndReturns) {
-            checkParamsAndReturnsTags();
-        }
-        else if (aliasDeclaration.type === 'ClassDeclaration') {
-            /* c8 ignore next -- TS */
-            for (const nde of aliasDeclaration?.body?.body ?? []) {
-                // @ts-expect-error Should be ok
-                const commentNode = (0, jsdoccomment_1.getJSDocComment)(sourceCode, nde, settings);
-                if (!commentNode) {
-                    continue;
-                }
-                const innerJsdoc = (0, iterateJsdoc_js_1.parseComment)(commentNode, '');
-                checkParamsAndReturnsTags(innerJsdoc);
-                const typeName = /** @type {string} */ (utils.getPreferredTagName({
-                    tagName: 'type',
-                }));
-                const typeTags = (0, jsdocUtils_js_1.getTags)(innerJsdoc, typeName);
-                for (const typeTag of typeTags) {
-                    checkForUsedTypes(typeTag.type);
-                }
-            }
-        }
-        checkTemplateTags();
-    };
-    const handleTypeAliases = () => {
-        const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (node);
-        if (!nde) {
-            return;
-        }
-        switch (nde.type) {
-            case 'ClassDeclaration':
-            case 'TSInterfaceDeclaration':
-            case 'TSTypeAliasDeclaration':
-                checkParameters(nde);
-                break;
-            case 'ExportDefaultDeclaration':
-            case 'ExportNamedDeclaration':
-                switch (nde.declaration?.type) {
-                    case 'ClassDeclaration':
-                    case 'TSInterfaceDeclaration':
-                    case 'TSTypeAliasDeclaration':
-                        checkParameters(nde.declaration);
-                        break;
-                    case 'FunctionDeclaration':
-                        checkParameters(nde.declaration, true);
-                        break;
-                }
-                break;
-            case 'FunctionDeclaration':
-                checkParameters(nde, true);
-                break;
-        }
-    };
-    const callbackTags = utils.getTags('callback');
-    const functionTags = utils.getTags('function');
-    if (callbackTags.length || functionTags.length) {
-        checkParamsAndReturnsTags();
-        checkTemplateTags();
-        return;
-    }
-    const typedefTags = utils.getTags('typedef');
-    if (!typedefTags.length || typedefTags.length >= 2) {
-        handleTypeAliases();
-        return;
-    }
-    const potentialTypedefType = typedefTags[0].type;
-    checkForUsedTypes(potentialTypedefType);
-    const propertyName = /** @type {string} */ (utils.getPreferredTagName({
-        tagName: 'property',
-    }));
-    const propertyTags = utils.getTags(propertyName);
-    for (const propertyTag of propertyTags) {
-        checkForUsedTypes(propertyTag.type);
-    }
-    checkTemplateTags();
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Checks that any `@template` names are actually used in the connected `@typedef` or type alias.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-template-names.md#repos-sticky-header',
-        },
-        schema: [],
-        type: 'suggestion',
-    },
-});