@api-extractor-tools/eslint-plugin 0.1.0-alpha.1 → 0.1.0-alpha.2

package/ARCHITECTURE.md

@@ -97,11 +97,14 @@ Requires the TypeScript `override` keyword when the `@override` TSDoc tag is pre
 
 ### package-documentation
 
-Requires `@packageDocumentation` tag in files.
+Enforces correct usage of the `@packageDocumentation` tag based on whether a file is a package entry point (barrel file). The rule automatically detects entry points by examining the nearest `package.json`.
+
+- **Barrel files** (entry points): Requires `@packageDocumentation` tag to be present.
+- **Non-barrel files**: Reports an error if `@packageDocumentation` tag is found.
 
 **Options:** None
 
-Note: This rule checks all files ESLint runs it on. To only check entry points, configure ESLint's `files` option or use the Node.js utilities to conditionally enable the rule.
+Note: This rule uses `findPackageJson` and `isEntryPoint` from the entry-point utilities to determine barrel file status. If no `package.json` is found, the rule is skipped.
 
 ## Usage Examples
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @api-extractor-tools/eslint-plugin
 
+## 0.1.0-alpha.2
+
+### Minor Changes
+
+- [#204](https://github.com/mike-north/api-extractor-tools/pull/204) [`3accc97`](https://github.com/mike-north/api-extractor-tools/commit/3accc97733d1b21eb7bbbe82b122a347e9b5ea76) Thanks [@mike-north](https://github.com/mike-north)! - fix: enforce @packageDocumentation only on package barrel files
+
+  The `package-documentation` rule now automatically detects whether a file is a package entry point by examining the nearest `package.json`. Barrel files are required to have the `@packageDocumentation` tag, and non-barrel files report an error if the tag is present. Previously the rule required the tag on every file regardless of whether it was an entry point.
+
 ## 0.1.0-alpha.1
 
 ### Patch Changes

package/dist/rules/index.d.ts

@@ -6,5 +6,15 @@
  * All available ESLint rules.
  * @alpha
  */
-export declare const rules: { readonly 'extra-release-tag': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"extraReleaseTag", [import("./extra-release-tag").ExtraReleaseTagRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'forgotten-export': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"forgottenExport", [import("./forgotten-export").ForgottenExportRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'incompatible-release-tags': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"incompatibleReleaseTags", [import("./incompatible-release-tags").IncompatibleReleaseTagsRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'missing-release-tag': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingReleaseTag", [import("..").MissingReleaseTagRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'override-keyword': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingOverrideKeyword", [import("..").OverrideKeywordRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'package-documentation': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingPackageDocumentation", [import("..").PackageDocumentationRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'public-on-non-exported': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"publicOnNonExported", [import("./public-on-non-exported").PublicOnNonExportedRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'public-on-private-member': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"publicOnPrivateMember", [import("./public-on-private-member").PublicOnPrivateMemberRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>; readonly 'valid-enum-type': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingValue" | "invalidValue" | "multipleEnumTypes" | "invalidConstruct" | "missingEnumType", [import("..").ValidEnumTypeRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener> };
+export declare const rules: {
+    readonly 'extra-release-tag': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"extraReleaseTag", [import("./extra-release-tag").ExtraReleaseTagRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'forgotten-export': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"forgottenExport", [import("./forgotten-export").ForgottenExportRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'incompatible-release-tags': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"incompatibleReleaseTags", [import("./incompatible-release-tags").IncompatibleReleaseTagsRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'missing-release-tag': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingReleaseTag", [import("..").MissingReleaseTagRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'override-keyword': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingOverrideKeyword", [import("..").OverrideKeywordRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'package-documentation': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingPackageDocumentation" | "unexpectedPackageDocumentation", [import("..").PackageDocumentationRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'public-on-non-exported': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"publicOnNonExported", [import("./public-on-non-exported").PublicOnNonExportedRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'public-on-private-member': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"publicOnPrivateMember", [import("./public-on-private-member").PublicOnPrivateMemberRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+    readonly 'valid-enum-type': import("@typescript-eslint/utils/dist/ts-eslint").RuleModule<"missingValue" | "invalidValue" | "multipleEnumTypes" | "invalidConstruct" | "missingEnumType", [import("..").ValidEnumTypeRuleOptions], unknown, import("@typescript-eslint/utils/dist/ts-eslint").RuleListener>;
+};
 //# sourceMappingURL=index.d.ts.map

package/dist/rules/package-documentation.d.ts

@@ -1,8 +1,11 @@
 /**
- * ESLint rule requiring @packageDocumentation in files.
+ * ESLint rule requiring @packageDocumentation in package barrel files
+ * and disallowing it in non-barrel files.
  * @internal
  */
 import { ESLintUtils } from '@typescript-eslint/utils';
 import type { PackageDocumentationRuleOptions } from '../types';
-export declare const packageDocumentation: ESLintUtils.RuleModule<"missingPackageDocumentation", [PackageDocumentationRuleOptions], unknown, ESLintUtils.RuleListener>;
+type MessageIds = 'missingPackageDocumentation' | 'unexpectedPackageDocumentation';
+export declare const packageDocumentation: ESLintUtils.RuleModule<MessageIds, [PackageDocumentationRuleOptions], unknown, ESLintUtils.RuleListener>;
+export {};
 //# sourceMappingURL=package-documentation.d.ts.map

package/dist/rules/package-documentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package-documentation.d.ts","sourceRoot":"","sources":["../../src/rules/package-documentation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAKtD,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAA;AAS/D,eAAO,MAAM,oBAAoB,6HA4C/B,CAAA"}
+{"version":3,"file":"package-documentation.d.ts","sourceRoot":"","sources":["../../src/rules/package-documentation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAMtD,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAA;AAO/D,KAAK,UAAU,GACX,6BAA6B,GAC7B,gCAAgC,CAAA;AAEpC,eAAO,MAAM,oBAAoB,0GA+E/B,CAAA"}

package/dist/rules/package-documentation.js

@@ -1,22 +1,26 @@
 "use strict";
 /**
- * ESLint rule requiring @packageDocumentation in files.
+ * ESLint rule requiring @packageDocumentation in package barrel files
+ * and disallowing it in non-barrel files.
  * @internal
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.packageDocumentation = void 0;
+const path = require("path");
 const utils_1 = require("@typescript-eslint/utils");
 const tsdoc_parser_1 = require("../utils/tsdoc-parser");
+const entry_point_1 = require("../utils/entry-point");
 const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/mike-north/api-extractor-tools/blob/main/tools/eslint-plugin/docs/rules/${name}.md`);
 exports.packageDocumentation = createRule({
     name: 'package-documentation',
     meta: {
         type: 'suggestion',
         docs: {
-            description: 'Require @packageDocumentation tag in files',
+            description: 'Require @packageDocumentation tag in package barrel files and disallow it in non-barrel files',
         },
         messages: {
             missingPackageDocumentation: 'File is missing a @packageDocumentation comment. Add a TSDoc comment with @packageDocumentation at the top of the file.',
+            unexpectedPackageDocumentation: '@packageDocumentation comment should only be in the package barrel file, not in this file.',
         },
         schema: [
             {
@@ -29,19 +33,46 @@ exports.packageDocumentation = createRule({
     defaultOptions: [{}],
     create(context) {
         const sourceCode = context.sourceCode;
+        const filename = context.filename;
         return {
             Program(node) {
+                // Find the nearest package.json to determine barrel file status
+                const fileDir = path.dirname(path.resolve(filename));
+                const pkgPath = (0, entry_point_1.findPackageJson)(fileDir);
+                // If no package.json is found, we can't determine barrel file status
+                if (!pkgPath) {
+                    return;
+                }
+                const isBarrel = (0, entry_point_1.isEntryPoint)(filename, pkgPath);
                 const tsdocComments = (0, tsdoc_parser_1.findAllTSDocComments)(sourceCode);
-                for (const { parsed } of tsdocComments) {
-                    if (parsed.docComment && (0, tsdoc_parser_1.hasPackageDocumentation)(parsed.docComment)) {
-                        return;
+                if (isBarrel) {
+                    // Barrel files must have @packageDocumentation
+                    for (const { parsed } of tsdocComments) {
+                        if (parsed.docComment &&
+                            (0, tsdoc_parser_1.hasPackageDocumentation)(parsed.docComment)) {
+                            return;
+                        }
+                    }
+                    context.report({
+                        node,
+                        loc: { line: 1, column: 0 },
+                        messageId: 'missingPackageDocumentation',
+                    });
+                }
+                else {
+                    // Non-barrel files must NOT have @packageDocumentation
+                    for (const { comment, parsed } of tsdocComments) {
+                        if (parsed.docComment &&
+                            (0, tsdoc_parser_1.hasPackageDocumentation)(parsed.docComment)) {
+                            context.report({
+                                node,
+                                loc: comment.loc,
+                                messageId: 'unexpectedPackageDocumentation',
+                            });
+                            return;
+                        }
                     }
                 }
-                context.report({
-                    node,
-                    loc: { line: 1, column: 0 },
-                    messageId: 'missingPackageDocumentation',
-                });
             },
         };
     },

package/dist/rules/package-documentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"package-documentation.js","sourceRoot":"","sources":["../../src/rules/package-documentation.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,oDAAsD;AACtD,wDAG8B;AAG9B,MAAM,UAAU,GAAG,mBAAW,CAAC,WAAW,CACxC,CAAC,IAAI,EAAE,EAAE,CACP,8FAA8F,IAAI,KAAK,CAC1G,CAAA;AAIY,QAAA,oBAAoB,GAAG,UAAU,CAG5C;IACA,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE;YACJ,WAAW,EAAE,4CAA4C;SAC1D;QACD,QAAQ,EAAE;YACR,2BAA2B,EACzB,yHAAyH;SAC5H;QACD,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE;gBACd,oBAAoB,EAAE,KAAK;aAC5B;SACF;KACF;IACD,cAAc,EAAE,CAAC,EAAE,CAAC;IACpB,MAAM,CAAC,OAAO;QACZ,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;QAErC,OAAO;YACL,OAAO,CAAC,IAAI;gBACV,MAAM,aAAa,GAAG,IAAA,mCAAoB,EAAC,UAAU,CAAC,CAAA;gBAEtD,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;oBACvC,IAAI,MAAM,CAAC,UAAU,IAAI,IAAA,sCAAuB,EAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;wBACpE,OAAM;oBACR,CAAC;gBACH,CAAC;gBAED,OAAO,CAAC,MAAM,CAAC;oBACb,IAAI;oBACJ,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;oBAC3B,SAAS,EAAE,6BAA6B;iBACzC,CAAC,CAAA;YACJ,CAAC;SACF,CAAA;IACH,CAAC;CACF,CAAC,CAAA"}
+{"version":3,"file":"package-documentation.js","sourceRoot":"","sources":["../../src/rules/package-documentation.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,6BAA4B;AAC5B,oDAAsD;AACtD,wDAG8B;AAC9B,sDAAoE;AAGpE,MAAM,UAAU,GAAG,mBAAW,CAAC,WAAW,CACxC,CAAC,IAAI,EAAE,EAAE,CACP,8FAA8F,IAAI,KAAK,CAC1G,CAAA;AAMY,QAAA,oBAAoB,GAAG,UAAU,CAG5C;IACA,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE;YACJ,WAAW,EACT,+FAA+F;SAClG;QACD,QAAQ,EAAE;YACR,2BAA2B,EACzB,yHAAyH;YAC3H,8BAA8B,EAC5B,4FAA4F;SAC/F;QACD,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE;gBACd,oBAAoB,EAAE,KAAK;aAC5B;SACF;KACF;IACD,cAAc,EAAE,CAAC,EAAE,CAAC;IACpB,MAAM,CAAC,OAAO;QACZ,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;QAEjC,OAAO;YACL,OAAO,CAAC,IAAI;gBACV,gEAAgE;gBAChE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;gBACpD,MAAM,OAAO,GAAG,IAAA,6BAAe,EAAC,OAAO,CAAC,CAAA;gBAExC,qEAAqE;gBACrE,IAAI,CAAC,OAAO,EAAE,CAAC;oBACb,OAAM;gBACR,CAAC;gBAED,MAAM,QAAQ,GAAG,IAAA,0BAAY,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;gBAChD,MAAM,aAAa,GAAG,IAAA,mCAAoB,EAAC,UAAU,CAAC,CAAA;gBAEtD,IAAI,QAAQ,EAAE,CAAC;oBACb,+CAA+C;oBAC/C,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;wBACvC,IACE,MAAM,CAAC,UAAU;4BACjB,IAAA,sCAAuB,EAAC,MAAM,CAAC,UAAU,CAAC,EAC1C,CAAC;4BACD,OAAM;wBACR,CAAC;oBACH,CAAC;oBAED,OAAO,CAAC,MAAM,CAAC;wBACb,IAAI;wBACJ,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;wBAC3B,SAAS,EAAE,6BAA6B;qBACzC,CAAC,CAAA;gBACJ,CAAC;qBAAM,CAAC;oBACN,uDAAuD;oBACvD,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;wBAChD,IACE,MAAM,CAAC,UAAU;4BACjB,IAAA,sCAAuB,EAAC,MAAM,CAAC,UAAU,CAAC,EAC1C,CAAC;4BACD,OAAO,CAAC,MAAM,CAAC;gCACb,IAAI;gCACJ,GAAG,EAAE,OAAO,CAAC,GAAG;gCAChB,SAAS,EAAE,gCAAgC;6BAC5C,CAAC,CAAA;4BACF,OAAM;wBACR,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;SACF,CAAA;IACH,CAAC;CACF,CAAC,CAAA"}

package/dist/types.d.ts

@@ -24,9 +24,23 @@ export interface MessageConfig {
  * @alpha
  */
 export interface ApiExtractorMessagesConfig {
-    compilerMessageReporting?: { [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
-    extractorMessageReporting?: { 'ae-extra-release-tag'?: MessageConfig; 'ae-forgotten-export'?: MessageConfig; 'ae-incompatible-release-tags'?: MessageConfig; 'ae-internal-missing-underscore'?: MessageConfig; 'ae-missing-release-tag'?: MessageConfig; [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
-    tsdocMessageReporting?: { [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
+    compilerMessageReporting?: {
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
+    extractorMessageReporting?: {
+        'ae-extra-release-tag'?: MessageConfig;
+        'ae-forgotten-export'?: MessageConfig;
+        'ae-incompatible-release-tags'?: MessageConfig;
+        'ae-internal-missing-underscore'?: MessageConfig;
+        'ae-missing-release-tag'?: MessageConfig;
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
+    tsdocMessageReporting?: {
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
 }
 /**
  * Partial representation of api-extractor.json relevant for this plugin.
@@ -80,9 +94,9 @@ export type OverrideKeywordRuleOptions = Record<string, never>;
  * Options for the package-documentation rule.
  *
  * @remarks
- * By default, checks all files. Node.js users can use the `/node` entry point
- * utilities to determine if a file is a package entry point and conditionally
- * enable this rule.
+ * Automatically detects whether a file is a package entry point by examining
+ * the nearest package.json. Requires `@packageDocumentation` on barrel files
+ * and reports an error if the tag is found on non-barrel files.
  *
  * @alpha
  */

package/dist/utils/tsdoc-parser.d.ts

@@ -74,9 +74,7 @@ export declare function extractEnumType(commentText: string): EnumTypeExtraction
  * @returns The comment text if a TSDoc comment exists, undefined otherwise
  * @alpha
  */
-export declare function getLeadingTSDocComment(sourceCode: {
-    getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[];
-}, node: TSESTree.Node): string | undefined;
+export declare function getLeadingTSDocComment(sourceCode: { getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[] }, node: TSESTree.Node): string | undefined;
 /**
  * Finds all TSDoc comments in a source file.
  *
@@ -84,9 +82,7 @@ export declare function getLeadingTSDocComment(sourceCode: {
  * @returns Array of comment objects with their parsed content
  * @alpha
  */
-export declare function findAllTSDocComments(sourceCode: {
-    getAllComments: () => TSESTree.Comment[];
-}): Array<{
+export declare function findAllTSDocComments(sourceCode: { getAllComments: () => TSESTree.Comment[] }): Array<{
     comment: TSESTree.Comment;
     parsed: ParserContext;
 }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-extractor-tools/eslint-plugin",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "ESLint plugin providing authoring-time feedback for API Extractor",
   "main": "dist/index.js",
   "types": "dist/eslint-plugin-public.d.ts",
@@ -41,7 +41,7 @@
     "tsd": "^0.33.0",
     "typescript": "5.8.3",
     "vitest": "^4.0.15",
-    "@api-extractor-tools/declaration-file-normalizer": "0.0.1-alpha.2"
+    "@api-extractor-tools/declaration-file-normalizer": "0.1.0-alpha.6"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/rules/package-documentation.ts

@@ -1,13 +1,16 @@
 /**
- * ESLint rule requiring @packageDocumentation in files.
+ * ESLint rule requiring @packageDocumentation in package barrel files
+ * and disallowing it in non-barrel files.
  * @internal
  */
 
+import * as path from 'path'
 import { ESLintUtils } from '@typescript-eslint/utils'
 import {
   findAllTSDocComments,
   hasPackageDocumentation,
 } from '../utils/tsdoc-parser'
+import { findPackageJson, isEntryPoint } from '../utils/entry-point'
 import type { PackageDocumentationRuleOptions } from '../types'
 
 const createRule = ESLintUtils.RuleCreator(
@@ -15,7 +18,9 @@ const createRule = ESLintUtils.RuleCreator(
     `https://github.com/mike-north/api-extractor-tools/blob/main/tools/eslint-plugin/docs/rules/${name}.md`,
 )
 
-type MessageIds = 'missingPackageDocumentation'
+type MessageIds =
+  | 'missingPackageDocumentation'
+  | 'unexpectedPackageDocumentation'
 
 export const packageDocumentation = createRule<
   [PackageDocumentationRuleOptions],
@@ -25,11 +30,14 @@ export const packageDocumentation = createRule<
   meta: {
     type: 'suggestion',
     docs: {
-      description: 'Require @packageDocumentation tag in files',
+      description:
+        'Require @packageDocumentation tag in package barrel files and disallow it in non-barrel files',
     },
     messages: {
       missingPackageDocumentation:
         'File is missing a @packageDocumentation comment. Add a TSDoc comment with @packageDocumentation at the top of the file.',
+      unexpectedPackageDocumentation:
+        '@packageDocumentation comment should only be in the package barrel file, not in this file.',
     },
     schema: [
       {
@@ -42,22 +50,54 @@ export const packageDocumentation = createRule<
   defaultOptions: [{}],
   create(context) {
     const sourceCode = context.sourceCode
+    const filename = context.filename
 
     return {
       Program(node): void {
+        // Find the nearest package.json to determine barrel file status
+        const fileDir = path.dirname(path.resolve(filename))
+        const pkgPath = findPackageJson(fileDir)
+
+        // If no package.json is found, we can't determine barrel file status
+        if (!pkgPath) {
+          return
+        }
+
+        const isBarrel = isEntryPoint(filename, pkgPath)
         const tsdocComments = findAllTSDocComments(sourceCode)
 
-        for (const { parsed } of tsdocComments) {
-          if (parsed.docComment && hasPackageDocumentation(parsed.docComment)) {
-            return
+        if (isBarrel) {
+          // Barrel files must have @packageDocumentation
+          for (const { parsed } of tsdocComments) {
+            if (
+              parsed.docComment &&
+              hasPackageDocumentation(parsed.docComment)
+            ) {
+              return
+            }
           }
-        }
 
-        context.report({
-          node,
-          loc: { line: 1, column: 0 },
-          messageId: 'missingPackageDocumentation',
-        })
+          context.report({
+            node,
+            loc: { line: 1, column: 0 },
+            messageId: 'missingPackageDocumentation',
+          })
+        } else {
+          // Non-barrel files must NOT have @packageDocumentation
+          for (const { comment, parsed } of tsdocComments) {
+            if (
+              parsed.docComment &&
+              hasPackageDocumentation(parsed.docComment)
+            ) {
+              context.report({
+                node,
+                loc: comment.loc,
+                messageId: 'unexpectedPackageDocumentation',
+              })
+              return
+            }
+          }
+        }
       },
     }
   },

package/src/types.ts

@@ -108,9 +108,9 @@ export type OverrideKeywordRuleOptions = Record<string, never>
  * Options for the package-documentation rule.
  *
  * @remarks
- * By default, checks all files. Node.js users can use the `/node` entry point
- * utilities to determine if a file is a package entry point and conditionally
- * enable this rule.
+ * Automatically detects whether a file is a package entry point by examining
+ * the nearest package.json. Requires `@packageDocumentation` on barrel files
+ * and reports an error if the tag is found on non-barrel files.
  *
  * @alpha
  */

package/temp/eslint-plugin.api.md

@@ -42,11 +42,25 @@ export type ApiExtractorLogLevel = 'error' | 'none' | 'warning';
 // @alpha
 export interface ApiExtractorMessagesConfig {
     // (undocumented)
-    compilerMessageReporting?: { [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
+    compilerMessageReporting?: {
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
     // (undocumented)
-    extractorMessageReporting?: { 'ae-extra-release-tag'?: MessageConfig; 'ae-forgotten-export'?: MessageConfig; 'ae-incompatible-release-tags'?: MessageConfig; 'ae-internal-missing-underscore'?: MessageConfig; 'ae-missing-release-tag'?: MessageConfig; [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
+    extractorMessageReporting?: {
+        'ae-extra-release-tag'?: MessageConfig;
+        'ae-forgotten-export'?: MessageConfig;
+        'ae-incompatible-release-tags'?: MessageConfig;
+        'ae-internal-missing-underscore'?: MessageConfig;
+        'ae-missing-release-tag'?: MessageConfig;
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
     // (undocumented)
-    tsdocMessageReporting?: { [messageId: string]: MessageConfig | undefined; default?: MessageConfig };
+    tsdocMessageReporting?: {
+        [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
+    };
 }
 
 // @alpha
@@ -73,9 +87,7 @@ export interface ExtraReleaseTagRuleOptions {
 }
 
 // @alpha
-export function findAllTSDocComments(sourceCode: {
-    getAllComments: () => TSESTree.Comment[];
-}): Array<{
+export function findAllTSDocComments(sourceCode: { getAllComments: () => TSESTree.Comment[] }): Array<{
     comment: TSESTree.Comment;
     parsed: ParserContext;
 }>;
@@ -86,9 +98,7 @@ export interface ForgottenExportRuleOptions {
 }
 
 // @alpha
-export function getLeadingTSDocComment(sourceCode: {
-    getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[];
-}, node: TSESTree.Node): string | undefined;
+export function getLeadingTSDocComment(sourceCode: { getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[] }, node: TSESTree.Node): string | undefined;
 
 // @alpha @override
 export function hasOverrideTag(docComment: DocComment): boolean;
@@ -157,7 +167,17 @@ export interface ResolvedEntryPoints {
 }
 
 // @alpha
-export const rules: { readonly 'extra-release-tag': RuleModule<"extraReleaseTag", [ExtraReleaseTagRuleOptions], unknown, RuleListener>; readonly 'forgotten-export': RuleModule<"forgottenExport", [ForgottenExportRuleOptions], unknown, RuleListener>; readonly 'incompatible-release-tags': RuleModule<"incompatibleReleaseTags", [IncompatibleReleaseTagsRuleOptions], unknown, RuleListener>; readonly 'missing-release-tag': RuleModule<"missingReleaseTag", [MissingReleaseTagRuleOptions], unknown, RuleListener>; readonly 'override-keyword': RuleModule<"missingOverrideKeyword", [OverrideKeywordRuleOptions], unknown, RuleListener>; readonly 'package-documentation': RuleModule<"missingPackageDocumentation", [PackageDocumentationRuleOptions], unknown, RuleListener>; readonly 'public-on-non-exported': RuleModule<"publicOnNonExported", [PublicOnNonExportedRuleOptions], unknown, RuleListener>; readonly 'public-on-private-member': RuleModule<"publicOnPrivateMember", [PublicOnPrivateMemberRuleOptions], unknown, RuleListener>; readonly 'valid-enum-type': RuleModule<"missingValue" | "invalidValue" | "multipleEnumTypes" | "invalidConstruct" | "missingEnumType", [ValidEnumTypeRuleOptions], unknown, RuleListener> };
+export const rules: {
+    readonly 'extra-release-tag': RuleModule<"extraReleaseTag", [ExtraReleaseTagRuleOptions], unknown, RuleListener>;
+    readonly 'forgotten-export': RuleModule<"forgottenExport", [ForgottenExportRuleOptions], unknown, RuleListener>;
+    readonly 'incompatible-release-tags': RuleModule<"incompatibleReleaseTags", [IncompatibleReleaseTagsRuleOptions], unknown, RuleListener>;
+    readonly 'missing-release-tag': RuleModule<"missingReleaseTag", [MissingReleaseTagRuleOptions], unknown, RuleListener>;
+    readonly 'override-keyword': RuleModule<"missingOverrideKeyword", [OverrideKeywordRuleOptions], unknown, RuleListener>;
+    readonly 'package-documentation': RuleModule<"missingPackageDocumentation" | "unexpectedPackageDocumentation", [PackageDocumentationRuleOptions], unknown, RuleListener>;
+    readonly 'public-on-non-exported': RuleModule<"publicOnNonExported", [PublicOnNonExportedRuleOptions], unknown, RuleListener>;
+    readonly 'public-on-private-member': RuleModule<"publicOnPrivateMember", [PublicOnPrivateMemberRuleOptions], unknown, RuleListener>;
+    readonly 'valid-enum-type': RuleModule<"missingValue" | "invalidValue" | "multipleEnumTypes" | "invalidConstruct" | "missingEnumType", [ValidEnumTypeRuleOptions], unknown, RuleListener>;
+};
 
 // @alpha
 export interface ValidEnumTypeRuleOptions {

package/test/rules/package-documentation.test.ts

@@ -1,7 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, expect, afterAll, afterEach, beforeEach } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
 import * as path from 'path'
 import * as fs from 'fs'
 import * as os from 'os'
+import { packageDocumentation } from '../../src/rules/package-documentation.js'
 import {
   findPackageJson,
   isEntryPoint,
@@ -12,9 +15,49 @@ import {
   parseTSDocComment,
 } from '../../src/utils/tsdoc-parser.js'
 
+// Wire up vitest for RuleTester
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+// Create a temp directory for RuleTester tests (must exist at module eval time)
+const ruleTestDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eslint-pd-rule-'))
+const ruleTestSrcDir = path.join(ruleTestDir, 'src')
+fs.mkdirSync(ruleTestSrcDir, { recursive: true })
+fs.mkdirSync(path.join(ruleTestSrcDir, 'utils'), { recursive: true })
+
+fs.writeFileSync(
+  path.join(ruleTestDir, 'package.json'),
+  JSON.stringify({ name: 'test-package', main: './src/index.ts' }, null, 2),
+)
+
+// Create placeholder files so paths resolve correctly
+fs.writeFileSync(path.join(ruleTestSrcDir, 'index.ts'), '')
+fs.writeFileSync(path.join(ruleTestSrcDir, 'helper.ts'), '')
+fs.writeFileSync(path.join(ruleTestSrcDir, 'utils', 'deep.ts'), '')
+
+const entryFile = path.join(ruleTestSrcDir, 'index.ts')
+const helperFile = path.join(ruleTestSrcDir, 'helper.ts')
+const deepFile = path.join(ruleTestSrcDir, 'utils', 'deep.ts')
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslintParser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
 describe('package-documentation', () => {
   let tempDir: string
 
+  afterAll(() => {
+    fs.rmSync(ruleTestDir, { recursive: true, force: true })
+    clearPackageJsonCache()
+  })
+
   beforeEach(() => {
     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eslint-plugin-test-'))
     clearPackageJsonCache()
@@ -87,68 +130,72 @@ describe('package-documentation', () => {
     })
   })
 
-  describe('rule logic simulation', () => {
-    it('should pass when entry point has @packageDocumentation', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-      const indexPath = path.join(srcDir, 'index.ts')
-
-      const code = `/**
- * This is the main entry point.
+  ruleTester.run('package-documentation', packageDocumentation, {
+    valid: [
+      // Entry point with @packageDocumentation — should pass
+      {
+        code: `/**
+ * Package entry point.
  * @packageDocumentation
  */
-
-export function foo() {}`
-
-      fs.writeFileSync(indexPath, code)
-
-      const pkgPath = findPackageJson(srcDir)
-      expect(isEntryPoint(indexPath, pkgPath!)).toBe(true)
-
-      // Simulate checking for @packageDocumentation
-      const parsed = parseTSDocComment(`/**
- * This is the main entry point.
+export function foo() {}`,
+        filename: entryFile,
+      },
+      // Non-entry-point without @packageDocumentation — should pass
+      {
+        code: `/**
+ * A helper function.
+ */
+export function helper() {}`,
+        filename: helperFile,
+      },
+      // Non-entry-point with no comments at all — should pass
+      {
+        code: `export function helper() {}`,
+        filename: helperFile,
+      },
+      // Deep non-entry-point without @packageDocumentation — should pass
+      {
+        code: `export const x = 1`,
+        filename: deepFile,
+      },
+    ],
+    invalid: [
+      // Entry point without @packageDocumentation — should fail
+      {
+        code: `/**
+ * Missing package documentation.
+ */
+export function foo() {}`,
+        filename: entryFile,
+        errors: [{ messageId: 'missingPackageDocumentation' as const }],
+      },
+      // Entry point with no comments at all — should fail
+      {
+        code: `export function foo() {}`,
+        filename: entryFile,
+        errors: [{ messageId: 'missingPackageDocumentation' as const }],
+      },
+      // Non-entry-point with @packageDocumentation — should fail
+      {
+        code: `/**
+ * This shouldn't be here.
  * @packageDocumentation
- */`)
-      expect(hasPackageDocumentation(parsed.docComment)).toBe(true)
-    })
-
-    it('should fail when entry point lacks @packageDocumentation', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-      const indexPath = path.join(srcDir, 'index.ts')
-
-      const code = `/**
- * This is the main entry point.
  */
-
-export function foo() {}`
-
-      fs.writeFileSync(indexPath, code)
-
-      const pkgPath = findPackageJson(srcDir)
-      expect(isEntryPoint(indexPath, pkgPath!)).toBe(true)
-
-      // Simulate checking for @packageDocumentation
-      const parsed = parseTSDocComment(`/**
- * This is the main entry point.
- */`)
-      expect(hasPackageDocumentation(parsed.docComment)).toBe(false)
-    })
-
-    it('should not require @packageDocumentation for non-entry points', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-
-      const indexPath = path.join(srcDir, 'index.ts')
-      fs.writeFileSync(indexPath, '/** @packageDocumentation */ export {}')
-
-      const helperPath = path.join(srcDir, 'helper.ts')
-      fs.writeFileSync(helperPath, '// No package documentation needed')
-
-      const pkgPath = findPackageJson(srcDir)
-      // Helper is not an entry point, so no check needed
-      expect(isEntryPoint(helperPath, pkgPath!)).toBe(false)
-    })
+export function helper() {}`,
+        filename: helperFile,
+        errors: [{ messageId: 'unexpectedPackageDocumentation' as const }],
+      },
+      // Deep non-entry-point with @packageDocumentation — should fail
+      {
+        code: `/**
+ * Wrong place for package docs.
+ * @packageDocumentation
+ */
+export const x = 1`,
+        filename: deepFile,
+        errors: [{ messageId: 'unexpectedPackageDocumentation' as const }],
+      },
+    ],
   })
 })