eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/validTypes.js

@@ -1,333 +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 jsdoccomment_1 = require("@es-joy/jsdoccomment");
-const inlineTags = new Set([
-    'link', 'linkcode', 'linkplain',
-    'tutorial',
-]);
-const jsdocTypePrattKeywords = new Set([
-    'extends',
-    'import',
-    'is',
-    'readonly',
-    'typeof',
-]);
-const asExpression = /as\s+/v;
-const suppressTypes = new Set([
-    // https://github.com/google/closure-compiler/wiki/@suppress-annotations
-    // https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/ParserConfig.properties#L154
-    'accessControls',
-    'checkDebuggerStatement',
-    'checkEs5InheritanceCorrectnessConditions',
-    'checkPrototypalTypes',
-    'checkRegExp',
-    'checkTypes',
-    'checkVars',
-    'closureClassChecks',
-    'closureDepMethodUsageChecks',
-    'const',
-    'constantProperty',
-    'dangerousUnrecognizedTypeError',
-    'deprecated',
-    'duplicate',
-    'es5Strict',
-    'externsValidation',
-    'extraProvide',
-    'extraRequire',
-    'globalThis',
-    'invalidCasts',
-    'lateProvide',
-    'legacyGoogScopeRequire',
-    'lintChecks',
-    'lintVarDeclarations',
-    'messageConventions',
-    'misplacedTypeAnnotation',
-    'missingOverride',
-    'missingPolyfill',
-    'missingProperties',
-    'missingProvide',
-    'missingRequire',
-    'missingReturn',
-    'missingSourcesWarnings',
-    'moduleLoad',
-    'msgDescriptions',
-    'nonStandardJsDocs',
-    'partialAlias',
-    'polymer',
-    'reportUnknownTypes',
-    'strictCheckTypes',
-    'strictMissingProperties',
-    'strictModuleDepCheck',
-    'strictPrimitiveOperators',
-    'suspiciousCode',
-    // Not documented in enum
-    'switch',
-    'transitionalSuspiciousCodeWarnings',
-    'undefinedNames',
-    'undefinedVars',
-    'underscore',
-    'unknownDefines',
-    'untranspilableFeatures',
-    'unusedLocalVariables',
-    // Not documented?
-    'unusedPrivateMembers',
-    'uselessCode',
-    'useOfGoogProvide',
-    'visibility',
-    'with',
-]);
-/**
- * @param {string} path
- * @returns {boolean}
- */
-const tryParsePathIgnoreError = (path) => {
-    try {
-        (0, jsdoccomment_1.tryParse)(path);
-        return true;
-    }
-    catch {
-        // Keep the original error for including the whole type
-    }
-    return false;
-};
-// eslint-disable-next-line complexity
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, settings, utils, }) => {
-    const { allowEmptyNamepaths = false, } = context.options[0] || {};
-    const { mode, } = settings;
-    for (const tag of jsdoc.tags) {
-        /**
-         * @param {string} namepath
-         * @param {string} [tagName]
-         * @returns {boolean}
-         */
-        const validNamepathParsing = function (namepath, tagName) {
-            if (tryParsePathIgnoreError(namepath) ||
-                jsdocTypePrattKeywords.has(namepath)) {
-                return true;
-            }
-            let handled = false;
-            if (tagName) {
-                switch (tagName) {
-                    case 'memberof':
-                    case 'memberof!': {
-                        const endChar = namepath.slice(-1);
-                        if ([
-                            '#', '.', '~',
-                        ].includes(endChar)) {
-                            handled = tryParsePathIgnoreError(namepath.slice(0, -1));
-                        }
-                        break;
-                    }
-                    case 'module':
-                    case 'requires': {
-                        if (!namepath.startsWith('module:')) {
-                            handled = tryParsePathIgnoreError(`module:${namepath}`);
-                        }
-                        break;
-                    }
-                    case 'borrows': {
-                        const startChar = namepath.charAt(0);
-                        if ([
-                            '#', '.', '~',
-                        ].includes(startChar)) {
-                            handled = tryParsePathIgnoreError(namepath.slice(1));
-                        }
-                    }
-                }
-            }
-            if (!handled) {
-                report(`Syntax error in namepath: ${namepath}`, null, tag);
-                return false;
-            }
-            return true;
-        };
-        /**
-         * @param {string} type
-         * @returns {boolean}
-         */
-        const validTypeParsing = function (type) {
-            let parsedTypes;
-            try {
-                if (mode === 'permissive') {
-                    parsedTypes = (0, jsdoccomment_1.tryParse)(type);
-                }
-                else {
-                    parsedTypes = (0, jsdoccomment_1.parse)(type, mode);
-                }
-            }
-            catch {
-                report(`Syntax error in type: ${type}`, null, tag);
-                return false;
-            }
-            if (mode === 'closure' || mode === 'typescript') {
-                (0, jsdoccomment_1.traverse)(parsedTypes, (node) => {
-                    const { type: typ, } = node;
-                    if ((typ === 'JsdocTypeObjectField' || typ === 'JsdocTypeKeyValue') &&
-                        node.right?.type === 'JsdocTypeNullable' &&
-                        node.right?.meta?.position === 'suffix') {
-                        report(`Syntax error in type: ${node.right.type}`, null, tag);
-                    }
-                });
-            }
-            return true;
-        };
-        if (tag.problems.length) {
-            const msg = tag.problems.reduce((str, { message, }) => {
-                return str + '; ' + message;
-            }, '').slice(2);
-            report(`Invalid name: ${msg}`, null, tag);
-            continue;
-        }
-        if (tag.tag === 'import') {
-            // A named import will look like a type, but not be valid; we also don't
-            //  need to check the name/namepath
-            continue;
-        }
-        if (tag.tag === 'borrows') {
-            const thisNamepath = /** @type {string} */ (utils.getTagDescription(tag)).replace(asExpression, '')
-                .trim();
-            if (!asExpression.test(/** @type {string} */ (utils.getTagDescription(tag))) || !thisNamepath) {
-                report(`@borrows must have an "as" expression. Found "${utils.getTagDescription(tag)}"`, null, tag);
-                continue;
-            }
-            if (validNamepathParsing(thisNamepath, 'borrows')) {
-                const thatNamepath = tag.name;
-                validNamepathParsing(thatNamepath);
-            }
-            continue;
-        }
-        if (tag.tag === 'suppress' && mode === 'closure') {
-            let parsedTypes;
-            try {
-                parsedTypes = (0, jsdoccomment_1.tryParse)(tag.type);
-            }
-            catch {
-                // Ignore
-            }
-            if (parsedTypes) {
-                (0, jsdoccomment_1.traverse)(parsedTypes, (node) => {
-                    let type;
-                    if ('value' in node && typeof node.value === 'string') {
-                        type = node.value;
-                    }
-                    if (type !== undefined && !suppressTypes.has(type)) {
-                        report(`Syntax error in suppress type: ${type}`, null, tag);
-                    }
-                });
-            }
-        }
-        const otherModeMaps = /** @type {import('../jsdocUtils.js').ParserMode[]} */ ([
-            'jsdoc', 'typescript', 'closure', 'permissive',
-        ]).filter((mde) => {
-            return mde !== mode;
-        }).map((mde) => {
-            return utils.getTagStructureForMode(mde);
-        });
-        const tagMightHaveNamePosition = utils.tagMightHaveNamePosition(tag.tag, otherModeMaps);
-        if (tagMightHaveNamePosition !== true && tag.name) {
-            const modeInfo = tagMightHaveNamePosition === false ? '' : ` in "${mode}" mode`;
-            report(`@${tag.tag} should not have a name${modeInfo}.`, null, tag);
-            continue;
-        }
-        // Documentation like `@returns {@link SomeType}` is technically ambiguous. Specifically it
-        // could either be intepreted as a type `"@link SomeType"` or a description `"{@link SomeType}"`.
-        // However this is a good heuristic.
-        if (tag.type.trim().startsWith('@')) {
-            tag.description = `{${tag.type}} ${tag.description}`;
-            tag.type = '';
-        }
-        const mightHaveTypePosition = utils.tagMightHaveTypePosition(tag.tag, otherModeMaps);
-        if (mightHaveTypePosition !== true && tag.type) {
-            const modeInfo = mightHaveTypePosition === false ? '' : ` in "${mode}" mode`;
-            report(`@${tag.tag} should not have a bracketed type${modeInfo}.`, null, tag);
-            continue;
-        }
-        // REQUIRED NAME
-        const tagMustHaveNamePosition = utils.tagMustHaveNamePosition(tag.tag, otherModeMaps);
-        // Don't handle `@param` here though it does require name as handled by
-        //  `require-param-name` (`@property` would similarly seem to require one,
-        //  but is handled by `require-property-name`)
-        if (tagMustHaveNamePosition !== false && !tag.name && !allowEmptyNamepaths && ![
-            'arg', 'argument', 'param',
-            'prop', 'property',
-        ].includes(tag.tag) &&
-            (tag.tag !== 'see' || !utils.getTagDescription(tag).includes('{@link'))) {
-            const modeInfo = tagMustHaveNamePosition === true ? '' : ` in "${mode}" mode`;
-            report(`Tag @${tag.tag} must have a name/namepath${modeInfo}.`, null, tag);
-            continue;
-        }
-        // REQUIRED TYPE
-        const mustHaveTypePosition = utils.tagMustHaveTypePosition(tag.tag, otherModeMaps);
-        if (mustHaveTypePosition !== false && !tag.type) {
-            const modeInfo = mustHaveTypePosition === true ? '' : ` in "${mode}" mode`;
-            report(`Tag @${tag.tag} must have a type${modeInfo}.`, null, tag);
-            continue;
-        }
-        // REQUIRED TYPE OR NAME/NAMEPATH
-        const tagMissingRequiredTypeOrNamepath = utils.tagMissingRequiredTypeOrNamepath(tag, otherModeMaps);
-        if (tagMissingRequiredTypeOrNamepath !== false && !allowEmptyNamepaths) {
-            const modeInfo = tagMissingRequiredTypeOrNamepath === true ? '' : ` in "${mode}" mode`;
-            report(`Tag @${tag.tag} must have either a type or namepath${modeInfo}.`, null, tag);
-            continue;
-        }
-        // VALID TYPE
-        const hasTypePosition = mightHaveTypePosition === true && Boolean(tag.type);
-        if (hasTypePosition) {
-            validTypeParsing(tag.type);
-        }
-        // VALID NAME/NAMEPATH
-        const hasNameOrNamepathPosition = (tagMustHaveNamePosition !== false ||
-            utils.tagMightHaveNamepath(tag.tag)) && Boolean(tag.name);
-        if (hasNameOrNamepathPosition) {
-            if (mode !== 'jsdoc' && tag.tag === 'template') {
-                if (!tryParsePathIgnoreError(
-                // May be an issue with the commas of
-                //   `utils.parseClosureTemplateTag`, so first try a raw
-                //   value; we really need a proper parser instead, however.
-                tag.name.trim().replace(/^\[?(?<name>.*?)=.*$/v, '$<name>'))) {
-                    for (const namepath of utils.parseClosureTemplateTag(tag)) {
-                        validNamepathParsing(namepath);
-                    }
-                }
-            }
-            else {
-                validNamepathParsing(tag.name, tag.tag);
-            }
-        }
-        for (const inlineTag of tag.inlineTags) {
-            if (inlineTags.has(inlineTag.tag) && !inlineTag.text && !inlineTag.namepathOrURL) {
-                report(`Inline tag "${inlineTag.tag}" missing content`, null, tag);
-            }
-        }
-    }
-    for (const inlineTag of jsdoc.inlineTags) {
-        if (inlineTags.has(inlineTag.tag) && !inlineTag.text && !inlineTag.namepathOrURL) {
-            report(`Inline tag "${inlineTag.tag}" missing content`);
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Requires all types to be valid JSDoc or Closure compiler types without syntax errors.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/valid-types.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    allowEmptyNamepaths: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/tagNames.js

@@ -1,209 +0,0 @@
-"use strict";
-/**
- * @typedef {{
- *   [key: string]: string[]
- * }} AliasedTags
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.typeScriptTags = exports.jsdocTags = exports.closureTags = void 0;
-/**
- * @type {AliasedTags}
- */
-const jsdocTagsUndocumented = {
-    // Undocumented but present; see
-    // https://github.com/jsdoc/jsdoc/issues/1283#issuecomment-516816802
-    // https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js#L594
-    modifies: [],
-};
-/**
- * @type {AliasedTags}
- */
-const jsdocTags = {
-    ...jsdocTagsUndocumented,
-    abstract: [
-        'virtual',
-    ],
-    access: [],
-    alias: [],
-    async: [],
-    augments: [
-        'extends',
-    ],
-    author: [],
-    borrows: [],
-    callback: [],
-    class: [
-        'constructor',
-    ],
-    classdesc: [],
-    constant: [
-        'const',
-    ],
-    constructs: [],
-    copyright: [],
-    default: [
-        'defaultvalue',
-    ],
-    deprecated: [],
-    description: [
-        'desc',
-    ],
-    enum: [],
-    event: [],
-    example: [],
-    exports: [],
-    external: [
-        'host',
-    ],
-    file: [
-        'fileoverview',
-        'overview',
-    ],
-    fires: [
-        'emits',
-    ],
-    function: [
-        'func',
-        'method',
-    ],
-    generator: [],
-    global: [],
-    hideconstructor: [],
-    ignore: [],
-    implements: [],
-    inheritdoc: [],
-    // Allowing casing distinct from jsdoc `definitions.js` (required in Closure)
-    inheritDoc: [],
-    inner: [],
-    instance: [],
-    interface: [],
-    kind: [],
-    lends: [],
-    license: [],
-    listens: [],
-    member: [
-        'var',
-    ],
-    memberof: [],
-    'memberof!': [],
-    mixes: [],
-    mixin: [],
-    module: [],
-    name: [],
-    namespace: [],
-    override: [],
-    package: [],
-    param: [
-        'arg',
-        'argument',
-    ],
-    private: [],
-    property: [
-        'prop',
-    ],
-    protected: [],
-    public: [],
-    readonly: [],
-    requires: [],
-    returns: [
-        'return',
-    ],
-    see: [],
-    since: [],
-    static: [],
-    summary: [],
-    this: [],
-    throws: [
-        'exception',
-    ],
-    todo: [],
-    tutorial: [],
-    type: [],
-    typedef: [],
-    variation: [],
-    version: [],
-    yields: [
-        'yield',
-    ],
-};
-exports.jsdocTags = jsdocTags;
-/**
- * @type {AliasedTags}
- */
-const typeScriptTags = {
-    ...jsdocTags,
-    // https://github.com/microsoft/TypeScript/issues/22160
-    // https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag
-    import: [],
-    // https://www.typescriptlang.org/tsconfig/#stripInternal
-    internal: [],
-    // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#overload-support-in-jsdoc
-    overload: [],
-    // https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#satisfies-support-in-jsdoc
-    satisfies: [],
-    // `@template` is also in TypeScript per:
-    //      https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc
-    template: [],
-};
-exports.typeScriptTags = typeScriptTags;
-/**
- * @type {AliasedTags}
- */
-const undocumentedClosureTags = {
-    // These are in Closure source but not in jsdoc source nor in the Closure
-    //  docs: https://github.com/google/closure-compiler/blob/master/src/com/google/javascript/jscomp/parsing/Annotation.java
-    closurePrimitive: [],
-    customElement: [],
-    expose: [],
-    hidden: [],
-    idGenerator: [],
-    meaning: [],
-    mixinClass: [],
-    mixinFunction: [],
-    ngInject: [],
-    owner: [],
-    typeSummary: [],
-    wizaction: [],
-};
-const { 
-/* eslint-disable no-unused-vars */
-inheritdoc, internal, overload, 
-// Will be inverted to prefer `return`
-returns, satisfies, 
-/* eslint-enable no-unused-vars */
-...typeScriptTagsInClosure } = typeScriptTags;
-/**
- * @type {AliasedTags}
- */
-const closureTags = {
-    ...typeScriptTagsInClosure,
-    ...undocumentedClosureTags,
-    // From https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler
-    // These are all recognized in https://github.com/jsdoc/jsdoc/blob/master/packages/jsdoc/lib/jsdoc/tag/dictionary/definitions.js
-    //   except for the experimental `noinline` and the casing differences noted below
-    // Defined as a synonym of `const` in jsdoc `definitions.js`
-    define: [],
-    dict: [],
-    export: [],
-    externs: [],
-    final: [],
-    // With casing distinct from jsdoc `definitions.js`
-    implicitCast: [],
-    noalias: [],
-    nocollapse: [],
-    nocompile: [],
-    noinline: [],
-    nosideeffects: [],
-    polymer: [],
-    polymerBehavior: [],
-    preserve: [],
-    // Defined as a synonym of `interface` in jsdoc `definitions.js`
-    record: [],
-    return: [
-        'returns',
-    ],
-    struct: [],
-    suppress: [],
-    unrestricted: [],
-};
-exports.closureTags = closureTags;