eslint-plugin-tsdoc-require-2 1.0.2 → 1.0.4

package/README.md

@@ -1,106 +1,148 @@
 # eslint-plugin-tsdoc-require-2
 
-[![CI](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/ci.yml)
-[![Release](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/release.yml/badge.svg)](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/release.yml)
-[![Codecov](https://codecov.io/gh/Nick2bad4u/eslint-plugin-tsdoc-require-2/graph/badge.svg)](https://codecov.io/gh/Nick2bad4u/eslint-plugin-tsdoc-require-2)
-[![npm version](https://img.shields.io/npm/v/eslint-plugin-tsdoc-require-2)](https://www.npmjs.com/package/eslint-plugin-tsdoc-require-2)
-[![npm downloads](https://img.shields.io/npm/dm/eslint-plugin-tsdoc-require-2)](https://www.npmjs.com/package/eslint-plugin-tsdoc-require-2)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![CI](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/ci.yml)[![Release](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/release.yml/badge.svg)](https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/actions/workflows/release.yml)[![Codecov](https://codecov.io/gh/Nick2bad4u/eslint-plugin-tsdoc-require-2/graph/badge.svg)](https://codecov.io/gh/Nick2bad4u/eslint-plugin-tsdoc-require-2)[![npm version](https://img.shields.io/npm/v/eslint-plugin-tsdoc-require-2)](https://www.npmjs.com/package/eslint-plugin-tsdoc-require-2)[![npm downloads](https://img.shields.io/npm/dm/eslint-plugin-tsdoc-require-2)](https://www.npmjs.com/package/eslint-plugin-tsdoc-require-2)[![Node.js](https://img.shields.io/badge/node-%3E%3D20.19.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 
-Require TSDoc comments for exported TypeScript declarations.
+Require TSDoc comments and specific TSDoc tags on exported TypeScript declarations.
 
 ## Installation
 
-```sh
-npm install --save-dev eslint eslint-plugin-tsdoc-require-2 @typescript-eslint/parser typescript
+```bash
+npm i -D eslint-plugin-tsdoc-require-2
 ```
 
 ## Usage (Flat Config)
 
 ```js
-// eslint.config.mjs
-import tsParser from "@typescript-eslint/parser";
 import tsdocRequire from "eslint-plugin-tsdoc-require-2";
 
 export default [
-    {
-        files: ["**/*.ts", "**/*.tsx"],
-        languageOptions: {
-            parser: tsParser,
-        },
-        plugins: {
-            "tsdoc-require-2": tsdocRequire,
-        },
-        rules: {
-            "tsdoc-require-2/require": "error",
-        },
+  tsdocRequire.configs.recommended,
+  {
+    plugins: {
+      "tsdoc-require-2": tsdocRequire,
     },
+    rules: {
+      "tsdoc-require-2/require": "error",
+      "tsdoc-require-2/require-remarks": "error",
+    },
+  },
 ];
 ```
 
-You can also use the bundled recommended config:
+## Presets
+
+The matrix below is generated by `scripts/sync-presets-rules-matrix.mjs`.
+
+<!-- BEGIN_PRESETS_MATRIX -->
+
+| Preset | Rule count | Included rules | Typical use case |
+| --- | ---: | --- | --- |
+| `recommended` | 1 | `tsdoc-require-2/require` | Minimal baseline TSDoc enforcement. |
+| `detailed` | 2 | `tsdoc-require-2/require`, `tsdoc-require-2/require-remarks` | General code docs baseline with remarks included. |
+| `packages` | 3 | `tsdoc-require-2/require`, `tsdoc-require-2/require-remarks`, `tsdoc-require-2/require-package-documentation` | Library/package-focused baseline for package entry docs. |
+| `all` | 26 | `tsdoc-require-2/require`, `tsdoc-require-2/require-alpha`, `tsdoc-require-2/require-beta`, `tsdoc-require-2/require-decorator`, `tsdoc-require-2/require-default-value`, `tsdoc-require-2/require-deprecated`, `tsdoc-require-2/require-event-property`, `tsdoc-require-2/require-example`, `tsdoc-require-2/require-experimental`, `tsdoc-require-2/require-inherit-doc`, `tsdoc-require-2/require-internal`, `tsdoc-require-2/require-label`, `tsdoc-require-2/require-link`, `tsdoc-require-2/require-override`, `tsdoc-require-2/require-package-documentation`, `tsdoc-require-2/require-param`, `tsdoc-require-2/require-private-remarks`, `tsdoc-require-2/require-public`, `tsdoc-require-2/require-readonly`, `tsdoc-require-2/require-remarks`, `tsdoc-require-2/require-returns`, `tsdoc-require-2/require-sealed`, `tsdoc-require-2/require-see`, `tsdoc-require-2/require-throws`, `tsdoc-require-2/require-type-param`, `tsdoc-require-2/require-virtual` | Enable every rule shipped by this plugin. (NOT RECOMMENDED) |
+
+<!-- END_PRESETS_MATRIX -->
+
+### Preset usage examples
 
 ```js
-// eslint.config.mjs
 import tsdocRequire from "eslint-plugin-tsdoc-require-2";
 
-export default [tsdocRequire.configs.recommended];
+export default [
+  tsdocRequire.configs.detailed,
+  // or:
+  // tsdocRequire.configs.packages,
+  // tsdocRequire.configs.all,
+];
 ```
 
-## Options (`tsdoc-require-2/require`)
-
-This rule accepts one optional settings object:
-
-```ts
-type Options = [
-    {
-        enforceFor?: Array<
-            "class" |
-            "enum" |
-            "function" |
-            "interface" |
-            "object" |
-            "type" |
-            "variable"
-        >;
-    },
-];
+## Rules
+
+The table below is generated by `scripts/sync-readme-rules-table.mjs`.
+
+<!-- BEGIN_RULES_TABLE -->
+
+| Rule | Description | Recommended | Detailed | Packages | All |
+| --- | --- | :---: | :---: | :---: | :---: |
+| [`tsdoc-require-2/require`](./docs/rules/require.md) | require TSDoc comments for exported TypeScript declarations and default exports. | ✅ | ✅ | ✅ | ✅ |
+| [`tsdoc-require-2/require-alpha`](./docs/rules/required-tags/require-alpha.md) | require @alpha tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-beta`](./docs/rules/required-tags/require-beta.md) | require @beta tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-decorator`](./docs/rules/required-tags/require-decorator.md) | require @decorator tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-default-value`](./docs/rules/required-tags/require-default-value.md) | require @defaultValue tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-deprecated`](./docs/rules/required-tags/require-deprecated.md) | require @deprecated tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-event-property`](./docs/rules/required-tags/require-event-property.md) | require @eventProperty tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-example`](./docs/rules/required-tags/require-example.md) | require @example tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-experimental`](./docs/rules/required-tags/require-experimental.md) | require @experimental tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-inherit-doc`](./docs/rules/required-tags/require-inherit-doc.md) | require @inheritDoc tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-internal`](./docs/rules/required-tags/require-internal.md) | require @internal tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-label`](./docs/rules/required-tags/require-label.md) | require @label tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-link`](./docs/rules/required-tags/require-link.md) | require @link tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-override`](./docs/rules/required-tags/require-override.md) | require @override tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-package-documentation`](./docs/rules/required-tags/require-package-documentation.md) | require @packageDocumentation tag in TSDoc blocks for exported declarations. | — | — | ✅ | ✅ |
+| [`tsdoc-require-2/require-param`](./docs/rules/required-tags/require-param.md) | require @param tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-private-remarks`](./docs/rules/required-tags/require-private-remarks.md) | require @privateRemarks tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-public`](./docs/rules/required-tags/require-public.md) | require @public tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-readonly`](./docs/rules/required-tags/require-readonly.md) | require @readonly tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-remarks`](./docs/rules/required-tags/require-remarks.md) | require @remarks tag in TSDoc blocks for exported declarations. | — | ✅ | ✅ | ✅ |
+| [`tsdoc-require-2/require-returns`](./docs/rules/required-tags/require-returns.md) | require @returns tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-sealed`](./docs/rules/required-tags/require-sealed.md) | require @sealed tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-see`](./docs/rules/required-tags/require-see.md) | require @see tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-throws`](./docs/rules/required-tags/require-throws.md) | require @throws tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-type-param`](./docs/rules/required-tags/require-type-param.md) | require @typeParam tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+| [`tsdoc-require-2/require-virtual`](./docs/rules/required-tags/require-virtual.md) | require @virtual tag in TSDoc blocks for exported declarations. | — | — | — | ✅ |
+
+<!-- END_RULES_TABLE -->
+
+## Rule docs
+
+- Core rule: [docs/rules/require.md](./docs/rules/require.md)
+- Required-tag index: [docs/rules/required-tags.md](./docs/rules/required-tags.md)
+
+## Development helpers
+
+- Regenerate README sections:
+
+```bash
+npm run sync:readme
 ```
 
-Default:
+- Check README generated sections in CI:
 
-```ts
-[{ enforceFor: ["class", "enum", "function", "interface", "object", "type", "variable"] }]
+```bash
+npm run sync:readme:check
 ```
 
-Example: only require TSDoc on exported classes and functions.
+## License
 
-```js
-// eslint.config.mjs
-import tsParser from "@typescript-eslint/parser";
-import tsdocRequire from "eslint-plugin-tsdoc-require-2";
+MIT © Nick2bad4u
 
-export default [
-    {
-        files: ["**/*.ts", "**/*.tsx"],
-        languageOptions: {
-            parser: tsParser,
-        },
-        plugins: {
-            "tsdoc-require-2": tsdocRequire,
-        },
-        rules: {
-            "tsdoc-require-2/require": [
-                "error",
-                {
-                    enforceFor: ["class", "function"],
-                },
-            ],
-        },
-    },
-];
-```
+## Contributors ✨
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors.](https://img.shields.io/badge/all_contributors-5-orange.svg?style=flat-square)](#contributors-)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="25%"><a href="https://github.com/Nick2bad4u"><img src="https://avatars.githubusercontent.com/u/20943337?v=4?s=80" width="80px;" alt="Nick2bad4u"/><br /><sub><b>Nick2bad4u</b></sub></a><br /><a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/issues?q=author%3ANick2bad4u" title="Bug reports">🐛</a> <a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/commits?author=Nick2bad4u" title="Code">💻</a> <a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/commits?author=Nick2bad4u" title="Documentation">📖</a> <a href="#ideas-Nick2bad4u" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-Nick2bad4u" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-Nick2bad4u" title="Maintenance">🚧</a> <a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/pulls?q=is%3Apr+reviewed-by%3ANick2bad4u" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/commits?author=Nick2bad4u" title="Tests">⚠️</a> <a href="#tool-Nick2bad4u" title="Tools">🔧</a></td>
+      <td align="center" valign="top" width="25%"><a href="https://snyk.io/"><img src="https://avatars.githubusercontent.com/u/19733683?v=4?s=80" width="80px;" alt="Snyk bot"/><br /><sub><b>Snyk bot</b></sub></a><br /><a href="#security-snyk-bot" title="Security">🛡️</a> <a href="#infra-snyk-bot" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-snyk-bot" title="Maintenance">🚧</a> <a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/pulls?q=is%3Apr+reviewed-by%3Asnyk-bot" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="25%"><a href="https://www.stepsecurity.io/"><img src="https://avatars.githubusercontent.com/u/89328645?v=4?s=80" width="80px;" alt="StepSecurity Bot"/><br /><sub><b>StepSecurity Bot</b></sub></a><br /><a href="#security-step-security-bot" title="Security">🛡️</a> <a href="#infra-step-security-bot" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#maintenance-step-security-bot" title="Maintenance">🚧</a></td>
+      <td align="center" valign="top" width="25%"><a href="https://github.com/apps/dependabot"><img src="https://avatars.githubusercontent.com/in/29110?v=4?s=80" width="80px;" alt="dependabot[bot]"/><br /><sub><b>dependabot[bot]</b></sub></a><br /><a href="#infra-dependabot[bot]" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#security-dependabot[bot]" title="Security">🛡️</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="25%"><a href="https://github.com/apps/github-actions"><img src="https://avatars.githubusercontent.com/in/15368?v=4?s=80" width="80px;" alt="github-actions[bot]"/><br /><sub><b>github-actions[bot]</b></sub></a><br /><a href="https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/commits?author=github-actions[bot]" title="Code">💻</a> <a href="#infra-github-actions[bot]" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="#platform-github-actions[bot]" title="Packaging/porting to new platform">📦</a></td>
+    </tr>
+  </tbody>
+</table>
 
-## Rule
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
 
-- [`tsdoc-require-2/require`](docs/rules/require.md): Requires TSDoc comments for exported TypeScript declarations and default exports.
+<!-- ALL-CONTRIBUTORS-LIST:END -->

package/dist/internal/require-tag-factory.cjs

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionSchema = exports.enforceableEntityKinds = exports.defaultRuleOptions = exports.createTagRule = exports.createRequireTagRuleListener = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const createTagRule = 
+// eslint-disable-next-line total-functions/no-hidden-type-assertions -- RuleCreator generic is required to support plugin-specific docs.recommended metadata field.
+utils_1.ESLintUtils.RuleCreator((ruleName) => `https://github.com/Nick2bad4u/eslint-plugin-tsdoc-require-2/blob/main/docs/rules/required-tags.md#${ruleName}`);
+exports.createTagRule = createTagRule;
+const enforceableEntityKinds = [
+    "class",
+    "enum",
+    "function",
+    "interface",
+    "object",
+    "type",
+    "variable",
+];
+exports.enforceableEntityKinds = enforceableEntityKinds;
+const defaultEnforceFor = [...enforceableEntityKinds];
+const defaultRuleOptions = [
+    {
+        enforceFor: defaultEnforceFor,
+        includeNonExported: false,
+    },
+];
+exports.defaultRuleOptions = defaultRuleOptions;
+const optionSchema = {
+    additionalProperties: false,
+    properties: {
+        enforceFor: {
+            items: {
+                enum: [...enforceableEntityKinds],
+                type: "string",
+            },
+            type: "array",
+            uniqueItems: true,
+        },
+        includeNonExported: {
+            default: false,
+            description: "Also enforce on non-exported declarations (opt-in).",
+            type: "boolean",
+        },
+    },
+    type: "object",
+};
+exports.optionSchema = optionSchema;
+const assertUnreachable = (value) => {
+    throw new Error(`Unexpected node type: ${String(value)}`);
+};
+const isWordCharacter = (character) => {
+    if (character === undefined) {
+        return false;
+    }
+    return /\w/u.test(character);
+};
+const hasRequiredTag = (commentText, tagName) => {
+    let searchStartIndex = 0;
+    while (searchStartIndex < commentText.length) {
+        const tagIndex = commentText.indexOf(tagName, searchStartIndex);
+        if (tagIndex === -1) {
+            return false;
+        }
+        const beforeCharacter = tagIndex > 0 ? commentText[tagIndex - 1] : undefined;
+        const afterCharacter = commentText[tagIndex + tagName.length];
+        const hasBoundaryBefore = !isWordCharacter(beforeCharacter);
+        const hasBoundaryAfter = !isWordCharacter(afterCharacter);
+        if (hasBoundaryBefore && hasBoundaryAfter) {
+            return true;
+        }
+        searchStartIndex = tagIndex + tagName.length;
+    }
+    return false;
+};
+const getEntityDisplayName = (name) => name ?? "<default export>";
+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.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 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.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 createRequireTagRuleListener = (context, requiredTag) => {
+    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 includeNonExported = ruleOption?.includeNonExported ?? false;
+    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 (hasRequiredTag(commentNode.value, requiredTag)) {
+            return;
+        }
+        context.report({
+            data: {
+                entityKind: target.kind,
+                entityName: getEntityDisplayName(target.name),
+                tagName: requiredTag,
+            },
+            messageId: "missingTag",
+            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) {
+            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 (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 (includeNonExported && isSupportedDeclaration(statement)) {
+                    for (const target of declarationTargetsWithCommentNode(statement, statement)) {
+                        checkTarget(target);
+                    }
+                }
+                if (isSupportedDeclaration(statement)) {
+                    trackDeclarationTargets(statement);
+                    continue;
+                }
+                if (statement.type === utils_1.AST_NODE_TYPES.ExportNamedDeclaration &&
+                    statement.declaration !== null &&
+                    isSupportedDeclaration(statement.declaration)) {
+                    trackDeclarationTargets(statement.declaration);
+                }
+            }
+        },
+    };
+};
+exports.createRequireTagRuleListener = createRequireTagRuleListener;
+//# sourceMappingURL=require-tag-factory.js.map

package/dist/internal/require-tag-factory.d.ts

@@ -0,0 +1,26 @@
+import type { JSONSchema, TSESLint } from "@typescript-eslint/utils";
+import { ESLintUtils } from "@typescript-eslint/utils";
+type EntityKind = "class" | "enum" | "function" | "interface" | "object" | "type" | "variable";
+type RuleDocs = {
+    recommended: boolean;
+};
+type TagRuleContext = Readonly<TSESLint.RuleContext<TagRuleMessageIds, TagRuleOptions>>;
+type TagRuleModule = ESLintUtils.RuleModule<TagRuleMessageIds, TagRuleOptions, RuleDocs>;
+declare const createTagRule: ReturnType<typeof ESLintUtils.RuleCreator<RuleDocs>>;
+type RuleOption = {
+    enforceFor?: readonly EntityKind[];
+    includeNonExported?: boolean;
+};
+type TagRuleDefinition = {
+    readonly ruleName: string;
+    readonly tagName: `@${string}`;
+};
+type TagRuleMessageIds = "missingTag";
+type TagRuleOptions = [RuleOption];
+declare const enforceableEntityKinds: readonly EntityKind[];
+declare const defaultRuleOptions: TagRuleOptions;
+declare const optionSchema: JSONSchema.JSONSchema4;
+declare const createRequireTagRuleListener: (context: Readonly<TSESLint.RuleContext<TagRuleMessageIds, TagRuleOptions>>, requiredTag: `@${string}`) => TSESLint.RuleListener;
+export type { EntityKind, RuleDocs, RuleOption, TagRuleContext, TagRuleDefinition, TagRuleMessageIds, TagRuleModule, TagRuleOptions, };
+export { createRequireTagRuleListener, createTagRule, defaultRuleOptions, enforceableEntityKinds, optionSchema, };
+//# sourceMappingURL=require-tag-factory.d.ts.map

package/dist/internal/require-tag-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-tag-factory.d.ts","sourceRoot":"","sources":["../../src/internal/require-tag-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAY,MAAM,0BAA0B,CAAC;AAE/E,OAAO,EAGH,WAAW,EACd,MAAM,0BAA0B,CAAC;AAElC,KAAK,UAAU,GACT,OAAO,GACP,MAAM,GACN,UAAU,GACV,WAAW,GACX,QAAQ,GACR,MAAM,GACN,UAAU,CAAC;AAEjB,KAAK,QAAQ,GAAG;IACZ,WAAW,EAAE,OAAO,CAAC;CACxB,CAAC;AACF,KAAK,cAAc,GAAG,QAAQ,CAC1B,QAAQ,CAAC,WAAW,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAC1D,CAAC;AACF,KAAK,aAAa,GAAG,WAAW,CAAC,UAAU,CACvC,iBAAiB,EACjB,cAAc,EACd,QAAQ,CACX,CAAC;AAEF,QAAA,MAAM,aAAa,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,WAAW,CAAC,QAAQ,CAAC,CAKnE,CAAC;AAEN,KAAK,UAAU,GAAG;IACd,UAAU,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACnC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAiBF,KAAK,iBAAiB,GAAG;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,IAAI,MAAM,EAAE,CAAC;CAClC,CAAC;AAEF,KAAK,iBAAiB,GAAG,YAAY,CAAC;AAEtC,KAAK,cAAc,GAAG,CAAC,UAAU,CAAC,CAAC;AASnC,QAAA,MAAM,sBAAsB,EAAE,SAAS,UAAU,EAQhD,CAAC;AAIF,QAAA,MAAM,kBAAkB,EAAE,cAKzB,CAAC;AAEF,QAAA,MAAM,YAAY,EAAE,UAAU,CAAC,WAkB9B,CAAC;AAoNF,QAAA,MAAM,4BAA4B,GAC9B,SAAS,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC,EAC1E,aAAa,IAAI,MAAM,EAAE,KAC1B,QAAQ,CAAC,YA2JX,CAAC;AAEF,YAAY,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACjB,CAAC;AACF,OAAO,EACH,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,GACf,CAAC"}