eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/WarnSettings.d.ts

@@ -0,0 +1,16 @@
+export default WarnSettings;
+declare function WarnSettings(): {
+    /**
+     * Warn only once for each context and setting
+     * @param {{}} context
+     * @param {string} setting
+     * @returns {boolean}
+     */
+    hasBeenWarned(context: {}, setting: string): boolean;
+    /**
+     * @param {{}} context
+     * @param {string} setting
+     * @returns {void}
+     */
+    markSettingAsWarned(context: {}, setting: string): void;
+};

package/dist/cjs/WarnSettings.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const WarnSettings = function () {
+    /** @type {WeakMap<object, Set<string>>} */
+    const warnedSettings = new WeakMap();
+    return {
+        /**
+         * Warn only once for each context and setting
+         * @param {{}} context
+         * @param {string} setting
+         * @returns {boolean}
+         */
+        hasBeenWarned(context, setting) {
+            return warnedSettings.has(context) && /** @type {Set<string>} */ (warnedSettings.get(context)).has(setting);
+        },
+        /**
+         * @param {{}} context
+         * @param {string} setting
+         * @returns {void}
+         */
+        markSettingAsWarned(context, setting) {
+            // c8 ignore else
+            if (!warnedSettings.has(context)) {
+                warnedSettings.set(context, new Set());
+            }
+            /** @type {Set<string>} */ (warnedSettings.get(context)).add(setting);
+        },
+    };
+};
+exports.default = WarnSettings;

package/dist/cjs/alignTransform.d.ts

@@ -0,0 +1,33 @@
+export default alignTransform;
+export type TypelessInfo = {
+    hasNoTypes: boolean;
+    maxNamedTagLength: import("./iterateJsdoc.js").Integer;
+    maxUnnamedTagLength: import("./iterateJsdoc.js").Integer;
+};
+export type Width = {
+    name: import("./iterateJsdoc.js").Integer;
+    start: import("./iterateJsdoc.js").Integer;
+    tag: import("./iterateJsdoc.js").Integer;
+    type: import("./iterateJsdoc.js").Integer;
+};
+/**
+ * @param {{
+ *   customSpacings: import('../src/rules/checkLineAlignment.js').CustomSpacings,
+ *   tags: string[],
+ *   indent: string,
+ *   preserveMainDescriptionPostDelimiter: boolean,
+ *   wrapIndent: string,
+ *   disableWrapIndent: boolean,
+ * }} cfg
+ * @returns {(
+ *   block: import('comment-parser').Block
+ * ) => import('comment-parser').Block}
+ */
+declare function alignTransform({ customSpacings, disableWrapIndent, indent, preserveMainDescriptionPostDelimiter, tags, wrapIndent, }: {
+    customSpacings: import("../src/rules/checkLineAlignment.js").CustomSpacings;
+    tags: string[];
+    indent: string;
+    preserveMainDescriptionPostDelimiter: boolean;
+    wrapIndent: string;
+    disableWrapIndent: boolean;
+}): (block: import("comment-parser").Block) => import("comment-parser").Block;

package/dist/cjs/alignTransform.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * Transform based on https://github.com/syavorsky/comment-parser/blob/master/src/transforms/align.ts
+ *
+ * It contains some customizations to align based on the tags, and some custom options.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const comment_parser_1 = require("comment-parser");
+/**
+ * @typedef {{
+ *   hasNoTypes: boolean,
+ *   maxNamedTagLength: import('./iterateJsdoc.js').Integer,
+ *   maxUnnamedTagLength: import('./iterateJsdoc.js').Integer
+ * }} TypelessInfo
+ */
+const { rewireSource, } = comment_parser_1.util;
+/**
+ * @typedef {{
+ *   name: import('./iterateJsdoc.js').Integer,
+ *   start: import('./iterateJsdoc.js').Integer,
+ *   tag: import('./iterateJsdoc.js').Integer,
+ *   type: import('./iterateJsdoc.js').Integer
+ * }} Width
+ */
+/** @type {Width} */
+const zeroWidth = {
+    name: 0,
+    start: 0,
+    tag: 0,
+    type: 0,
+};
+/**
+ * @param {string[]} tags
+ * @param {import('./iterateJsdoc.js').Integer} index
+ * @param {import('comment-parser').Line[]} source
+ * @returns {boolean}
+ */
+const shouldAlign = (tags, index, source) => {
+    const tag = source[index].tokens.tag.replace('@', '');
+    const includesTag = tags.includes(tag);
+    if (includesTag) {
+        return true;
+    }
+    if (tag !== '') {
+        return false;
+    }
+    for (let iterator = index; iterator >= 0; iterator--) {
+        const previousTag = source[iterator].tokens.tag.replace('@', '');
+        if (previousTag !== '') {
+            if (tags.includes(previousTag)) {
+                return true;
+            }
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * @param {string[]} tags
+ * @returns {(
+ *   width: Width,
+ *   line: {
+ *     tokens: import('comment-parser').Tokens
+ *   },
+ *   index: import('./iterateJsdoc.js').Integer,
+ *   source: import('comment-parser').Line[]
+ * ) => Width}
+ */
+const getWidth = (tags) => {
+    return (width, { tokens, }, index, source) => {
+        if (!shouldAlign(tags, index, source)) {
+            return width;
+        }
+        return {
+            name: Math.max(width.name, tokens.name.length),
+            start: tokens.delimiter === '/**' ? tokens.start.length : width.start,
+            tag: Math.max(width.tag, tokens.tag.length),
+            type: Math.max(width.type, tokens.type.length),
+        };
+    };
+};
+/**
+ * @param {{
+ *   description: string;
+ *   tags: import('comment-parser').Spec[];
+ *   problems: import('comment-parser').Problem[];
+ * }} fields
+ * @returns {TypelessInfo}
+ */
+const getTypelessInfo = (fields) => {
+    const hasNoTypes = fields.tags.every(({ type, }) => {
+        return !type;
+    });
+    const maxNamedTagLength = Math.max(...fields.tags.map(({ name, tag, }) => {
+        return name.length === 0 ? -1 : tag.length;
+    }).filter((length) => {
+        return length !== -1;
+    })) + 1;
+    const maxUnnamedTagLength = Math.max(...fields.tags.map(({ name, tag, }) => {
+        return name.length === 0 ? tag.length : -1;
+    }).filter((length) => {
+        return length !== -1;
+    })) + 1;
+    return {
+        hasNoTypes,
+        maxNamedTagLength,
+        maxUnnamedTagLength,
+    };
+};
+/**
+ * @param {import('./iterateJsdoc.js').Integer} len
+ * @returns {string}
+ */
+const space = (len) => {
+    return ''.padStart(len, ' ');
+};
+/**
+ * @param {{
+ *   customSpacings: import('../src/rules/checkLineAlignment.js').CustomSpacings,
+ *   tags: string[],
+ *   indent: string,
+ *   preserveMainDescriptionPostDelimiter: boolean,
+ *   wrapIndent: string,
+ *   disableWrapIndent: boolean,
+ * }} cfg
+ * @returns {(
+ *   block: import('comment-parser').Block
+ * ) => import('comment-parser').Block}
+ */
+const alignTransform = ({ customSpacings, disableWrapIndent, indent, preserveMainDescriptionPostDelimiter, tags, wrapIndent, }) => {
+    let intoTags = false;
+    /** @type {Width} */
+    let width;
+    /**
+     * @param {import('comment-parser').Tokens} tokens
+     * @param {TypelessInfo} typelessInfo
+     * @returns {import('comment-parser').Tokens}
+     */
+    const alignTokens = (tokens, typelessInfo) => {
+        const nothingAfter = {
+            delim: false,
+            name: false,
+            tag: false,
+            type: false,
+        };
+        if (tokens.description === '') {
+            nothingAfter.name = true;
+            tokens.postName = '';
+            if (tokens.name === '') {
+                nothingAfter.type = true;
+                tokens.postType = '';
+                if (tokens.type === '') {
+                    nothingAfter.tag = true;
+                    tokens.postTag = '';
+                    /* c8 ignore next: Never happens because the !intoTags return. But it's here for consistency with the original align transform */
+                    if (tokens.tag === '') {
+                        nothingAfter.delim = true;
+                    }
+                }
+            }
+        }
+        let untypedNameAdjustment = 0;
+        let untypedTypeAdjustment = 0;
+        if (typelessInfo.hasNoTypes) {
+            nothingAfter.tag = true;
+            tokens.postTag = '';
+            if (tokens.name === '') {
+                untypedNameAdjustment = typelessInfo.maxNamedTagLength - tokens.tag.length;
+            }
+            else {
+                untypedNameAdjustment = typelessInfo.maxNamedTagLength > typelessInfo.maxUnnamedTagLength ? 0 :
+                    Math.max(0, typelessInfo.maxUnnamedTagLength - (tokens.tag.length + tokens.name.length + 1));
+                untypedTypeAdjustment = typelessInfo.maxNamedTagLength - tokens.tag.length;
+            }
+        }
+        // Todo: Avoid fixing alignment of blocks with multiline wrapping of type
+        if (tokens.tag === '' && tokens.type) {
+            return tokens;
+        }
+        const spacings = {
+            postDelimiter: customSpacings?.postDelimiter || 1,
+            postName: customSpacings?.postName || 1,
+            postTag: customSpacings?.postTag || 1,
+            postType: customSpacings?.postType || 1,
+        };
+        tokens.postDelimiter = nothingAfter.delim ? '' : space(spacings.postDelimiter);
+        if (!nothingAfter.tag) {
+            tokens.postTag = space(width.tag - tokens.tag.length + spacings.postTag);
+        }
+        if (!nothingAfter.type) {
+            tokens.postType = space(width.type - tokens.type.length + spacings.postType + untypedTypeAdjustment);
+        }
+        if (!nothingAfter.name) {
+            // If post name is empty for all lines (name width 0), don't add post name spacing.
+            tokens.postName = width.name === 0 ? '' : space(width.name - tokens.name.length + spacings.postName + untypedNameAdjustment);
+        }
+        return tokens;
+    };
+    /**
+     * @param {import('comment-parser').Line} line
+     * @param {import('./iterateJsdoc.js').Integer} index
+     * @param {import('comment-parser').Line[]} source
+     * @param {TypelessInfo} typelessInfo
+     * @param {string|false} indentTag
+     * @returns {import('comment-parser').Line}
+     */
+    const update = (line, index, source, typelessInfo, indentTag) => {
+        /** @type {import('comment-parser').Tokens} */
+        const tokens = {
+            ...line.tokens,
+        };
+        if (tokens.tag !== '') {
+            intoTags = true;
+        }
+        const isEmpty = tokens.tag === '' &&
+            tokens.name === '' &&
+            tokens.type === '' &&
+            tokens.description === '';
+        // dangling '*/'
+        if (tokens.end === '*/' && isEmpty) {
+            tokens.start = indent + ' ';
+            return {
+                ...line,
+                tokens,
+            };
+        }
+        switch (tokens.delimiter) {
+            case '*':
+                tokens.start = indent + ' ';
+                break;
+            case '/**':
+                tokens.start = indent;
+                break;
+            default:
+                tokens.delimiter = '';
+                // compensate delimiter
+                tokens.start = indent + '  ';
+        }
+        if (!intoTags) {
+            if (tokens.description === '') {
+                tokens.postDelimiter = '';
+            }
+            else if (!preserveMainDescriptionPostDelimiter) {
+                tokens.postDelimiter = ' ';
+            }
+            return {
+                ...line,
+                tokens,
+            };
+        }
+        const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
+        const hyphenSpacing = /^\s*-\s+/v;
+        tokens.description = tokens.description.replace(hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '));
+        // Not align.
+        if (shouldAlign(tags, index, source)) {
+            alignTokens(tokens, typelessInfo);
+            if (!disableWrapIndent && indentTag) {
+                tokens.postDelimiter += wrapIndent;
+            }
+        }
+        return {
+            ...line,
+            tokens,
+        };
+    };
+    return ({ source, ...fields }) => {
+        width = source.reduce(getWidth(tags), {
+            ...zeroWidth,
+        });
+        const typelessInfo = getTypelessInfo(fields);
+        let tagIndentMode = false;
+        return rewireSource({
+            ...fields,
+            source: source.map((line, index) => {
+                const indentTag = !disableWrapIndent && tagIndentMode && !line.tokens.tag && line.tokens.description;
+                const ret = update(line, index, source, typelessInfo, indentTag);
+                if (!disableWrapIndent && line.tokens.tag) {
+                    tagIndentMode = true;
+                }
+                return ret;
+            }),
+        });
+    };
+};
+exports.default = alignTransform;

package/dist/cjs/defaultTagOrder.d.ts

@@ -0,0 +1,4 @@
+export default defaultTagOrder;
+declare const defaultTagOrder: {
+    tags: string[];
+}[];

package/dist/cjs/defaultTagOrder.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const defaultTagOrder = [
+    {
+        tags: [
+            // Brief descriptions
+            'summary',
+            'typeSummary',
+            // Module/file-level
+            'module',
+            'exports',
+            'file',
+            'fileoverview',
+            'overview',
+            'import',
+            // Identifying (name, type)
+            'template',
+            'typedef',
+            'interface',
+            'record',
+            'name',
+            'kind',
+            'type',
+            'alias',
+            'external',
+            'host',
+            'callback',
+            'func',
+            'function',
+            'method',
+            'class',
+            'constructor',
+            // Relationships
+            'modifies',
+            'mixes',
+            'mixin',
+            'mixinClass',
+            'mixinFunction',
+            'namespace',
+            'borrows',
+            'constructs',
+            'lends',
+            'implements',
+            'requires',
+            // Long descriptions
+            'desc',
+            'description',
+            'classdesc',
+            'tutorial',
+            'copyright',
+            'license',
+            // Simple annotations
+            // TypeScript
+            'internal',
+            'overload',
+            'const',
+            'constant',
+            'final',
+            'global',
+            'readonly',
+            'abstract',
+            'virtual',
+            'var',
+            'member',
+            'memberof',
+            'memberof!',
+            'inner',
+            'instance',
+            'inheritdoc',
+            'inheritDoc',
+            'override',
+            'hideconstructor',
+            // Core function/object info
+            'param',
+            'arg',
+            'argument',
+            'prop',
+            'property',
+            'return',
+            'returns',
+            // Important behavior details
+            'async',
+            'generator',
+            'default',
+            'defaultvalue',
+            'enum',
+            'augments',
+            'extends',
+            'throws',
+            'exception',
+            'yield',
+            'yields',
+            'event',
+            'fires',
+            'emits',
+            'listens',
+            'this',
+            // TypeScript
+            'satisfies',
+            // Access
+            'static',
+            'private',
+            'protected',
+            'public',
+            'access',
+            'package',
+            '-other',
+            // Supplementary descriptions
+            'see',
+            'example',
+            // METADATA
+            // Other Closure (undocumented) metadata
+            'closurePrimitive',
+            'customElement',
+            'expose',
+            'hidden',
+            'idGenerator',
+            'meaning',
+            'ngInject',
+            'owner',
+            'wizaction',
+            // Other Closure (documented) metadata
+            'define',
+            'dict',
+            'export',
+            'externs',
+            'implicitCast',
+            'noalias',
+            'nocollapse',
+            'nocompile',
+            'noinline',
+            'nosideeffects',
+            'polymer',
+            'polymerBehavior',
+            'preserve',
+            'struct',
+            'suppress',
+            'unrestricted',
+            // @homer0/prettier-plugin-jsdoc metadata
+            'category',
+            // Non-Closure metadata
+            'ignore',
+            'author',
+            'version',
+            'variation',
+            'since',
+            'deprecated',
+            'todo',
+        ],
+    },
+];
+exports.default = defaultTagOrder;

package/dist/cjs/exportParser.d.ts

@@ -0,0 +1,40 @@
+declare namespace _default {
+    export { isUncommentedExport };
+    export { parse };
+}
+export default _default;
+export type ValueObject = {
+    value: string;
+};
+export type CreatedNode = {
+    type?: string;
+    value?: ValueObject | import("eslint").Rule.Node | import("@typescript-eslint/types").TSESTree.Node;
+    props: {
+        [key: string]: CreatedNode | null;
+    };
+    special?: true;
+    globalVars?: CreatedNode;
+    exported?: boolean;
+    ANONYMOUS_DEFAULT?: import("eslint").Rule.Node;
+};
+export type CreateSymbol = (node: import("eslint").Rule.Node | null, globals: CreatedNode, value: import("eslint").Rule.Node | import("@typescript-eslint/types").TSESTree.Node | null, scope?: CreatedNode | undefined, isGlobal?: boolean | SymbolOptions | undefined) => CreatedNode | null;
+export type SymbolOptions = {
+    simpleIdentifier?: boolean;
+};
+/**
+ *
+ * @param {import('eslint').Rule.Node} node
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('./rules/requireJsdoc.js').RequireJsdocOpts} opt
+ * @param {import('./iterateJsdoc.js').Settings} settings
+ * @returns {boolean}
+ */
+declare function isUncommentedExport(node: import("eslint").Rule.Node, sourceCode: import("eslint").SourceCode, opt: import("./rules/requireJsdoc.js").RequireJsdocOpts, settings: import("./iterateJsdoc.js").Settings): boolean;
+/**
+ *
+ * @param {import('eslint').Rule.Node} ast
+ * @param {import('eslint').Rule.Node} node
+ * @param {import('./rules/requireJsdoc.js').RequireJsdocOpts} opt
+ * @returns {CreatedNode}
+ */
+declare function parse(ast: import("eslint").Rule.Node, node: import("eslint").Rule.Node, opt: import("./rules/requireJsdoc.js").RequireJsdocOpts): CreatedNode;