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

package/dist/rules/restrict-tags.js

@@ -0,0 +1,414 @@
+import { AST_NODE_TYPES, AST_TOKEN_TYPES, ESLintUtils, } from "@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 = ESLintUtils.RuleCreator((ruleName) => `https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/blob/main/docs/rules/${ruleName}.md`);
+const isSupportedDeclaration = (node) => node.type === AST_NODE_TYPES.ClassDeclaration ||
+    node.type === AST_NODE_TYPES.FunctionDeclaration ||
+    node.type === AST_NODE_TYPES.TSDeclareFunction ||
+    node.type === AST_NODE_TYPES.TSEnumDeclaration ||
+    node.type === AST_NODE_TYPES.TSInterfaceDeclaration ||
+    node.type === AST_NODE_TYPES.TSModuleDeclaration ||
+    node.type === AST_NODE_TYPES.TSTypeAliasDeclaration ||
+    node.type === AST_NODE_TYPES.VariableDeclaration;
+const isSupportedDefaultExportExpression = (node) => node.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    node.type === AST_NODE_TYPES.ClassExpression ||
+    node.type === AST_NODE_TYPES.FunctionExpression ||
+    node.type === AST_NODE_TYPES.ObjectExpression;
+const getExpressionKind = (node) => {
+    if (node.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+        node.type === AST_NODE_TYPES.FunctionExpression) {
+        return "function";
+    }
+    if (node.type === AST_NODE_TYPES.ClassExpression) {
+        return "class";
+    }
+    if (node.type === AST_NODE_TYPES.ObjectExpression) {
+        return "object";
+    }
+    return assertUnreachable(node);
+};
+const getEntityDisplayName = (name) => name ?? "<default export>";
+const isTopLevelNode = (node) => node.parent?.type === AST_NODE_TYPES.Program;
+const getModuleDeclarationName = (declaration) => {
+    if (declaration.id.type === AST_NODE_TYPES.Identifier) {
+        return declaration.id.name;
+    }
+    if (declaration.id.type === 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 !== 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 === AST_NODE_TYPES.ClassDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "class",
+                name: declaration.id?.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.FunctionDeclaration ||
+        declaration.type === AST_NODE_TYPES.TSDeclareFunction) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "function",
+                name: declaration.id?.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.TSEnumDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "enum",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.TSInterfaceDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "interface",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.TSModuleDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "namespace",
+                name: getModuleDeclarationName(declaration),
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.TSTypeAliasDeclaration) {
+        return [
+            {
+                commentNode: declaration,
+                kind: "type",
+                name: declaration.id.name,
+                reportNode: declaration,
+            },
+        ];
+    }
+    if (declaration.type === AST_NODE_TYPES.VariableDeclaration) {
+        return declaration.declarations.flatMap((declarator) => {
+            if (declarator.id.type !== 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 === 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 !== 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 ===
+                            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",
+});
+export default restrictTagsRule;
+//# sourceMappingURL=restrict-tags.js.map

package/dist/rules/restrict-tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restrict-tags.js","sourceRoot":"","sources":["../../src/rules/restrict-tags.ts"],"names":[],"mappings":"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"}

package/docs/rules/getting-started.md

@@ -0,0 +1,97 @@
+# Getting Started
+
+`eslint-plugin-tsdoc-require-2` is easiest to adopt in layers:
+
+1. **Require docs to exist** with [`tsdoc-require-2/require`](./require.md).
+2. **Require specific tags** with one or more [`require-*` rules](./required-tags.md).
+3. **Restrict allowed tag vocabulary** with [`tsdoc-require-2/restrict-tags`](./restrict-tags.md).
+
+Starting from a preset gives you a stable baseline before you tune rule options.
+
+## 1) Install
+
+```bash
+npm install --save-dev eslint-plugin-tsdoc-require-2
+```
+
+## 2) Choose one preset baseline
+
+Pick **one** preset as your starting point:
+
+| Preset | Best for |
+| --- | --- |
+| [`recommended`](./presets/recommended.md) | Minimal rollout: require TSDoc comments only. |
+| [`detailed`](./presets/detailed.md) | Require comments + `@remarks` for richer docs. |
+| [`packages`](./presets/packages.md) | Package/library docs including `@packageDocumentation`. |
+| [`jsdoc`](./presets/jsdoc.md) | Function-tag baseline (`@param`, `@returns`, `@throws`) with JSDoc-friendly behavior. |
+| [`tsdoc`](./presets/tsdoc.md) | Strong TSDoc baseline with tag requirements + compatibility-tag restrictions. |
+| [`typedoc`](./presets/typedoc.md) | TypeDoc-oriented declaration-kind tag enforcement. |
+| [`typedoc-strict`](./presets/typedoc-strict.md) | Stricter TypeDoc baseline with module remarks and restricted tags. |
+| [`all`](./presets/all.md) | Every rule. Useful for audits, usually too strict for day-one adoption. |
+
+## 3) Enable a preset in Flat Config
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [tsdocRequire.configs.recommended];
+```
+
+## 4) Add targeted overrides (recommended)
+
+After selecting a preset, add a second config block to tune scope/options.
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+    tsdocRequire.configs.tsdoc,
+    {
+        rules: {
+            "tsdoc-require-2/require": [
+                "error",
+                {
+                    exportMode: "all",
+                },
+            ],
+            "tsdoc-require-2/restrict-tags": [
+                "error",
+                {
+                    exportMode: "all",
+                    mode: "deny",
+                    tags: ["@typedef", "@callback"],
+                },
+            ],
+        },
+    },
+];
+```
+
+## How to use the rules together
+
+Treat the rules as a pipeline:
+
+1. **Presence layer:** `require` ensures there is a TSDoc block.
+2. **Content layer:** `require-*` tag rules enforce required fields (for example `@param`).
+3. **Vocabulary layer:** `restrict-tags` blocks unsupported tags.
+
+### Important composition tip
+
+Keep `exportMode` and `enforceFor` aligned across rules. If one rule checks only exported declarations but another checks all declarations, your policy can feel inconsistent.
+
+### Important allow-mode tip
+
+When using `restrict-tags` with `mode: "allow"`, include every tag required by enabled `require-*` rules, or the rules will conflict.
+
+## Suggested rollout strategy
+
+1. Start with `recommended`.
+2. Add only the tag rules your team can consistently maintain (`@param`, `@returns`, `@throws`, `@remarks` are common first picks).
+3. Add `restrict-tags` only after your required-tag policy is stable.
+4. Expand from `exportMode: "exported"` to `"all"` when internal documentation quality is a goal.
+
+## Next steps
+
+- Compare presets in [Presets Overview](./presets/index.md).
+- Review [Rules Overview](./index.md).
+- Learn the foundational rule in [`tsdoc-require-2/require`](./require.md).

package/docs/rules/index.md

@@ -0,0 +1,61 @@
+---
+slug: /
+title: Rules
+description: Explore the comprehensive set of rules provided by eslint-plugin-tsdoc-require-2 to enforce TSDoc/JSDoc documentation standards in your TypeScript codebase.
+---
+
+# Rules
+
+`eslint-plugin-tsdoc-require-2` enforces API documentation with three complementary rule families.
+
+## Rule family overview
+
+| Family | Purpose | Start here when |
+| --- | --- | --- |
+| [`require`](./require.md) | Require a TSDoc block (`/** ... */`) on selected declarations. | You need a documentation baseline first. |
+| [`required-tags`](./required-tags.md) | Require specific tags (for example `@param`, `@returns`, `@remarks`) through individual `require-*` rules. | You want documentation completeness and consistency. |
+| [`restrict-tags`](./restrict-tags.md) | Allow-list or deny-list tags to control vocabulary and compatibility. | You need a strict tag policy (for example strict TSDoc vs loose JSDoc/TypeDoc tags). |
+
+## How the families work together
+
+Use them in this order:
+
+1. **Presence**: `require` ensures docs exist.
+2. **Completeness**: `require-*` rules ensure required tags exist.
+3. **Vocabulary**: `restrict-tags` ensures only approved tags are used.
+
+This sequencing reduces confusion because tag rules only matter once comments exist.
+
+## Practical configuration pattern
+
+Use a preset for the baseline, then add focused overrides.
+
+```ts
+import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+
+export default [
+	tsdocRequire.configs.recommended,
+	{
+		rules: {
+			"tsdoc-require-2/require-param": ["error", { enforceFor: ["function"] }],
+			"tsdoc-require-2/require-returns": ["error", { enforceFor: ["function"] }],
+			"tsdoc-require-2/restrict-tags": [
+				"error",
+				{
+					mode: "deny",
+					tags: ["@typedef", "@callback"],
+				},
+			],
+		},
+	},
+];
+```
+
+## Where to start
+
+- New adoption: [Getting Started](./getting-started.md)
+- Preset selection: [Presets Overview](./presets/index.md)
+- Rule family details:
+	- [`tsdoc-require-2/require`](./require.md)
+	- [`tsdoc-require-2/required-tags` family](./required-tags.md)
+	- [`tsdoc-require-2/restrict-tags`](./restrict-tags.md)