eslint-plugin-tsdoc-require-2 1.0.6 → 1.0.8

package/dist/rules/restrict-tags.cjs

@@ -0,0 +1,416 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const utils_1 = require("@typescript-eslint/utils");
+const enforceableEntityKinds = [
+    "class",
+    "enum",
+    "function",
+    "interface",
+    "namespace",
+    "object",
+    "type",
+    "variable",
+];
+const defaultRestrictedTags = [
+    "@augments",
+    "@callback",
+    "@extends",
+    "@jsx",
+    "@satisfies",
+    "@type",
+    "@typedef",
+    "@yields",
+];
+const defaultEnforceFor = [...enforceableEntityKinds];
+const optionSchema = {
+    additionalProperties: false,
+    properties: {
+        enforceFor: {
+            items: {
+                enum: [...enforceableEntityKinds],
+                type: "string",
+            },
+            type: "array",
+            uniqueItems: true,
+        },
+        exportMode: {
+            description: "Choose whether to check exported declarations, non-exported top-level declarations, or both.",
+            enum: [
+                "all",
+                "exported",
+                "non-exported",
+            ],
+            type: "string",
+        },
+        includeNonExported: {
+            default: false,
+            description: 'Legacy alias for exportMode: "all". Also enforce on non-exported declarations when true.',
+            type: "boolean",
+        },
+        mode: {
+            default: "deny",
+            description: "Tag restriction mode. deny = listed tags are disallowed. allow = only listed tags are permitted.",
+            enum: ["allow", "deny"],
+            type: "string",
+        },
+        tags: {
+            description: "Tag names used by the selected restriction mode.",
+            items: {
+                pattern: "^@[A-Za-z][A-Za-z0-9-]*$",
+                type: "string",
+            },
+            type: "array",
+            uniqueItems: true,
+        },
+    },
+    type: "object",
+};
+const resolveExportMode = (ruleOption) => {
+    if (ruleOption?.includeNonExported === true) {
+        return "all";
+    }
+    return ruleOption?.exportMode ?? "exported";
+};
+const shouldCheckExportedDeclarations = (exportMode) => exportMode === "all" || exportMode === "exported";
+const shouldCheckNonExportedDeclarations = (exportMode) => exportMode === "all" || exportMode === "non-exported";
+const assertUnreachable = (value) => {
+    throw new Error(`Unexpected node type: ${String(value)}`);
+};
+const createRule = utils_1.ESLintUtils.RuleCreator((ruleName) => `https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/blob/main/docs/rules/${ruleName}.md`);
+const isSupportedDeclaration = (node) => node.type === utils_1.AST_NODE_TYPES.ClassDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.TSDeclareFunction ||
+    node.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration ||
+    node.type === utils_1.AST_NODE_TYPES.VariableDeclaration;
+const isSupportedDefaultExportExpression = (node) => node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+    node.type === utils_1.AST_NODE_TYPES.ClassExpression ||
+    node.type === utils_1.AST_NODE_TYPES.FunctionExpression ||
+    node.type === utils_1.AST_NODE_TYPES.ObjectExpression;
+const getExpressionKind = (node) => {
+    if (node.type === utils_1.AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === utils_1.AST_NODE_TYPES.FunctionExpression) {
+        return "function";
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.ClassExpression) {
+        return "class";
+    }
+    if (node.type === utils_1.AST_NODE_TYPES.ObjectExpression) {
+        return "object";
+    }
+    return assertUnreachable(node);
+};
+const getEntityDisplayName = (name) => name ?? "<default export>";
+const isTopLevelNode = (node) => node.parent?.type === utils_1.AST_NODE_TYPES.Program;
+const getModuleDeclarationName = (declaration) => {
+    if (declaration.id.type === utils_1.AST_NODE_TYPES.Identifier) {
+        return declaration.id.name;
+    }
+    if (declaration.id.type === utils_1.AST_NODE_TYPES.Literal &&
+        typeof declaration.id.value === "string") {
+        return declaration.id.value;
+    }
+    return undefined;
+};
+const getTSDocCommentNode = (sourceCode, node) => {
+    const comments = sourceCode.getCommentsBefore(node);
+    const nearestComment = comments.at(-1);
+    if (nearestComment === undefined) {
+        return null;
+    }
+    if (nearestComment.type !== utils_1.AST_TOKEN_TYPES.Block) {
+        return null;
+    }
+    if (!nearestComment.value.startsWith("*")) {
+        return null;
+    }
+    const nearestCommentLoc = nearestComment.loc;
+    const nodeLoc = node.loc;
+    if (nearestCommentLoc === null || nodeLoc === null) {
+        return null;
+    }
+    const lineGap = nodeLoc.start.line - nearestCommentLoc.end.line;
+    if (lineGap < 0 || lineGap > 1) {
+        return null;
+    }
+    return nearestComment;
+};
+const createTargetKey = (target) => {
+    const [start, end] = target.reportNode.range;
+    return `${start}:${end}:${target.kind}:${target.name ?? ""}`;
+};
+const declarationTargets = (declaration) => {
+    if (declaration.type === utils_1.AST_NODE_TYPES.ClassDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "class",
+                name: declaration.id?.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.FunctionDeclaration ||
+        declaration.type === utils_1.AST_NODE_TYPES.TSDeclareFunction) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "function",
+                name: declaration.id?.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSEnumDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "enum",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSInterfaceDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "interface",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSModuleDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "namespace",
+                name: getModuleDeclarationName(declaration),
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "type",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === utils_1.AST_NODE_TYPES.VariableDeclaration) {
+        return declaration.declarations.flatMap((declarator) => {
+            if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+                return [];
+            }
+            return [
+                {
+                    commentNode: declaration,
+                    kind: "variable",
+                    name: declarator.id.name,
+                    reportNode: declarator,
+                },
+            ];
+        });
+    }
+    return assertUnreachable(declaration);
+};
+const declarationTargetsWithCommentNode = (declaration, commentNode) => declarationTargets(declaration).map((target) => ({
+    ...target,
+    commentNode,
+}));
+const extractTagNames = (commentText) => {
+    const tagPattern = /(?:^|\W)@(?<tagName>[A-Za-z][-0-9A-Za-z]*)/gu;
+    const extractedTagNames = new Set();
+    for (const match of commentText.matchAll(tagPattern)) {
+        const rawTagName = match.groups?.["tagName"];
+        if (rawTagName === undefined) {
+            continue;
+        }
+        extractedTagNames.add(`@${rawTagName}`);
+    }
+    return extractedTagNames;
+};
+const getConfiguredTagSet = (ruleOption) => {
+    const configuredTags = ruleOption?.tags ?? defaultRestrictedTags;
+    return new Set(configuredTags);
+};
+/** ESLint rule module implementing tsdoc-require-2/restrict-tags. */
+const restrictTagsRule = createRule({
+    create(context) {
+        const declarationsByName = new Map();
+        const checkedTargets = new Set();
+        const sourceCode = context.sourceCode;
+        const ruleOption = context.options.at(0);
+        const enabledKinds = new Set(ruleOption?.enforceFor ?? defaultEnforceFor);
+        const exportMode = resolveExportMode(ruleOption);
+        const restrictMode = ruleOption?.mode ?? "deny";
+        const configuredTagSet = getConfiguredTagSet(ruleOption);
+        const allowedTags = [...configuredTagSet];
+        const checkTarget = (target) => {
+            if (!enabledKinds.has(target.kind)) {
+                return;
+            }
+            const targetKey = createTargetKey(target);
+            if (checkedTargets.has(targetKey)) {
+                return;
+            }
+            checkedTargets.add(targetKey);
+            const commentNode = getTSDocCommentNode(sourceCode, target.commentNode);
+            if (commentNode === null) {
+                return;
+            }
+            if (configuredTagSet.size === 0) {
+                return;
+            }
+            const foundTags = extractTagNames(commentNode.value);
+            for (const tagName of foundTags) {
+                const isConfiguredTag = configuredTagSet.has(tagName);
+                if (restrictMode === "deny" && isConfiguredTag) {
+                    context.report({
+                        data: {
+                            entityKind: target.kind,
+                            entityName: getEntityDisplayName(target.name),
+                            tagName,
+                        },
+                        messageId: "disallowedTag",
+                        node: target.reportNode,
+                    });
+                    continue;
+                }
+                if (restrictMode === "allow" && !isConfiguredTag) {
+                    context.report({
+                        data: {
+                            allowedTags: allowedTags.length === 0
+                                ? "<none>"
+                                : allowedTags.join(", "),
+                            entityKind: target.kind,
+                            entityName: getEntityDisplayName(target.name),
+                            tagName,
+                        },
+                        messageId: "tagNotAllowed",
+                        node: target.reportNode,
+                    });
+                }
+            }
+        };
+        const checkDeclarationWithExportComment = (declaration, exportNode) => {
+            for (const target of declarationTargetsWithCommentNode(declaration, exportNode)) {
+                checkTarget(target);
+            }
+        };
+        const trackDeclarationTargets = (declaration) => {
+            for (const target of declarationTargets(declaration)) {
+                if (target.name === undefined) {
+                    continue;
+                }
+                declarationsByName.set(target.name, target);
+            }
+        };
+        const checkIdentifierExport = (identifier) => {
+            const target = declarationsByName.get(identifier.name);
+            if (target !== undefined) {
+                checkTarget(target);
+            }
+        };
+        return {
+            ExportDefaultDeclaration(exportNode) {
+                if (!shouldCheckExportedDeclarations(exportMode) ||
+                    !isTopLevelNode(exportNode)) {
+                    return;
+                }
+                const { declaration } = exportNode;
+                if (declaration.type === utils_1.AST_NODE_TYPES.Identifier) {
+                    checkIdentifierExport(declaration);
+                    return;
+                }
+                if (isSupportedDeclaration(declaration)) {
+                    checkDeclarationWithExportComment(declaration, exportNode);
+                    return;
+                }
+                if (isSupportedDefaultExportExpression(declaration)) {
+                    checkTarget({
+                        commentNode: exportNode,
+                        kind: getExpressionKind(declaration),
+                        name: undefined,
+                        reportNode: declaration,
+                    });
+                }
+            },
+            ExportNamedDeclaration(exportNode) {
+                if (!shouldCheckExportedDeclarations(exportMode) ||
+                    !isTopLevelNode(exportNode)) {
+                    return;
+                }
+                if (exportNode.declaration !== null &&
+                    isSupportedDeclaration(exportNode.declaration)) {
+                    checkDeclarationWithExportComment(exportNode.declaration, exportNode);
+                }
+                if (exportNode.source !== null) {
+                    return;
+                }
+                for (const specifier of exportNode.specifiers) {
+                    if (specifier.type !== utils_1.AST_NODE_TYPES.ExportSpecifier) {
+                        continue;
+                    }
+                    checkIdentifierExport(specifier.local);
+                }
+            },
+            Program(programNode) {
+                declarationsByName.clear();
+                checkedTargets.clear();
+                for (const statement of programNode.body) {
+                    if (isSupportedDeclaration(statement)) {
+                        if (shouldCheckNonExportedDeclarations(exportMode)) {
+                            for (const target of declarationTargetsWithCommentNode(statement, statement)) {
+                                checkTarget(target);
+                            }
+                        }
+                        if (shouldCheckExportedDeclarations(exportMode)) {
+                            trackDeclarationTargets(statement);
+                        }
+                        continue;
+                    }
+                    if (shouldCheckExportedDeclarations(exportMode) &&
+                        statement.type ===
+                            utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                        statement.declaration !== null &&
+                        isSupportedDeclaration(statement.declaration)) {
+                        trackDeclarationTargets(statement.declaration);
+                    }
+                }
+            },
+        };
+    },
+    meta: {
+        defaultOptions: [
+            {
+                enforceFor: [...enforceableEntityKinds],
+                exportMode: "exported",
+                mode: "deny",
+                tags: [...defaultRestrictedTags],
+            },
+        ],
+        deprecated: false,
+        docs: {
+            description: "disallow or allow only specific TSDoc/JSDoc tags in TSDoc blocks using configurable declaration scope.",
+            frozen: false,
+            recommended: false,
+            url: "https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/blob/main/docs/rules/restrict-tags.md",
+        },
+        messages: {
+            disallowedTag: "TSDoc for {{entityKind}} {{entityName}} contains disallowed tag {{tagName}}.",
+            tagNotAllowed: "TSDoc for {{entityKind}} {{entityName}} contains tag {{tagName}}, which is not in the allowed set: {{allowedTags}}.",
+        },
+        schema: [optionSchema],
+        type: "problem",
+    },
+    name: "restrict-tags",
+});
+exports.default = restrictTagsRule;
+//# sourceMappingURL=restrict-tags.js.map

package/dist/rules/restrict-tags.d.ts

@@ -0,0 +1,17 @@
+import type { TSESLint } from "@typescript-eslint/utils";
+type EntityKind = "class" | "enum" | "function" | "interface" | "namespace" | "object" | "type" | "variable";
+type ExportMode = "all" | "exported" | "non-exported";
+type MessageIds = "disallowedTag" | "tagNotAllowed";
+type Options = [RuleOption];
+type RestrictMode = "allow" | "deny";
+type RuleOption = {
+    enforceFor?: readonly EntityKind[];
+    exportMode?: ExportMode;
+    includeNonExported?: boolean;
+    mode?: RestrictMode;
+    tags?: readonly `@${string}`[];
+};
+/** ESLint rule module implementing tsdoc-require-2/restrict-tags. */
+declare const restrictTagsRule: TSESLint.RuleModule<MessageIds, Options>;
+export default restrictTagsRule;
+//# sourceMappingURL=restrict-tags.d.ts.map

package/dist/rules/restrict-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restrict-tags.d.ts","sourceRoot":"","sources":["../../src/rules/restrict-tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,QAAQ,EAAY,MAAM,0BAA0B,CAAC;AAQ/E,KAAK,UAAU,GACT,OAAO,GACP,MAAM,GACN,UAAU,GACV,WAAW,GACX,WAAW,GACX,QAAQ,GACR,MAAM,GACN,UAAU,CAAC;AACjB,KAAK,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,cAAc,CAAC;AACtD,KAAK,UAAU,GAAG,eAAe,GAAG,eAAe,CAAC;AAEpD,KAAK,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;AAC5B,KAAK,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAMrC,KAAK,UAAU,GAAG;IACd,UAAU,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACnC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,EAAE,SAAS,IAAI,MAAM,EAAE,EAAE,CAAC;CAClC,CAAC;AA2VF,qEAAqE;AACrE,QAAA,MAAM,gBAAgB,EAAE,QAAQ,CAAC,UAAU,CAAC,UAAU,EAAE,OAAO,CA4O7D,CAAC;AAEH,eAAe,gBAAgB,CAAC"}