eslint-plugin-jsdoc 55.4.0 → 56.0.0

package/dist/cjs/rules/validTypes.js

@@ -0,0 +1,333 @@
+"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.d.ts

@@ -0,0 +1,15 @@
+export type AliasedTags = {
+    [key: string]: string[];
+};
+/**
+ * @type {AliasedTags}
+ */
+export const closureTags: AliasedTags;
+/**
+ * @type {AliasedTags}
+ */
+export const jsdocTags: AliasedTags;
+/**
+ * @type {AliasedTags}
+ */
+export const typeScriptTags: AliasedTags;

package/dist/cjs/tagNames.js

@@ -0,0 +1,209 @@
+"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;

package/dist/cjs/utils/hasReturnValue.d.ts

@@ -0,0 +1,19 @@
+export type ESTreeOrTypeScriptNode = import("estree").Node | import("@typescript-eslint/types").TSESTree.Node;
+export type PromiseFilter = (node: ESTreeOrTypeScriptNode | undefined) => boolean;
+/**
+ * Checks if a node has a return statement. Void return does not count.
+ * @param {ESTreeOrTypeScriptNode|undefined|null} node
+ * @param {boolean} [throwOnNullReturn]
+ * @param {PromiseFilter} [promFilter]
+ * @returns {boolean|undefined}
+ */
+export function hasReturnValue(node: ESTreeOrTypeScriptNode | undefined | null, throwOnNullReturn?: boolean, promFilter?: PromiseFilter): boolean | undefined;
+/**
+ * Checks if a Promise executor has no resolve value or an empty value.
+ * An `undefined` resolve does not count.
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} anyPromiseAsReturn
+ * @param {boolean} [allBranches]
+ * @returns {boolean}
+ */
+export function hasValueOrExecutorHasNonEmptyResolveValue(node: ESTreeOrTypeScriptNode, anyPromiseAsReturn: boolean, allBranches?: boolean): boolean;