Add validation for multiple @module tags

- ModuleDocComment now accepts Collector parameter for error reporting
- Detects and reports error for multiple @module tags in same file
- Added MisplacedModuleTag error message ID
- Maintains silent skip behavior for @module on individual declarations

Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>

Author: Copilot

apps/api-extractor/src/aedoc/ModuleDocComment.ts

@@ -3,31 +3,50 @@
 
 import * as ts from 'typescript';
 
+import type { Collector } from '../collector/Collector';
+import { ExtractorMessageId } from '../api/ExtractorMessageId';
+
 export class ModuleDocComment {
   /**
    * For the given source file, see if it starts with a TSDoc comment containing the `@module` tag.
    */
-  public static tryFindInSourceFile(sourceFile: ts.SourceFile): ts.TextRange | undefined {
+  public static tryFindInSourceFile(
+    sourceFile: ts.SourceFile,
+    collector: Collector
+  ): ts.TextRange | undefined {
     // The @module comment is special because it is not attached to an AST
     // definition.  Instead, it is part of the "trivia" tokens that the compiler treats
     // as irrelevant white space.
     //
     // This implementation assumes that the "@module" will be in the first TSDoc comment
     // that appears in the source file.
     let moduleCommentRange: ts.TextRange | undefined = undefined;
+    let foundFirstJSDocComment: boolean = false;
 
     for (const commentRange of ts.getLeadingCommentRanges(sourceFile.text, sourceFile.getFullStart()) || []) {
       if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia) {
         const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);
 
         // Choose the first JSDoc-style comment
         if (/^\s*\/\*\*/.test(commentBody)) {
-          // But only if it looks like it's trying to be @module
-          // (The TSDoc parser will validate this more rigorously)
-          if (/\@module/i.test(commentBody)) {
-            moduleCommentRange = commentRange;
+          if (!foundFirstJSDocComment) {
+            foundFirstJSDocComment = true;
+            // But only if it looks like it's trying to be @module
+            // (The TSDoc parser will validate this more rigorously)
+            if (/\@module/i.test(commentBody)) {
+              moduleCommentRange = commentRange;
+            }
+          } else {
+            // If we find another JSDoc comment with @module, report an error
+            if (/\@module/i.test(commentBody)) {
+              collector.messageRouter.addAnalyzerIssueForPosition(
+                ExtractorMessageId.MisplacedModuleTag,
+                'The @module comment should only appear once at the top of the source file',
+                sourceFile,
+                commentRange.pos
+              );
+            }
           }
-          break;
         }
       }
     }

apps/api-extractor/src/api/ExtractorMessageId.ts

@@ -56,6 +56,11 @@ export enum ExtractorMessageId {
    */
   MisplacedPackageTag = 'ae-misplaced-package-tag',
 
+  /**
+   * "The `@module` comment must only appear on modules that are re-exported as namespaces."
+   */
+  MisplacedModuleTag = 'ae-misplaced-module-tag',
+
   /**
    * "The symbol ___ needs to be exported by the entry point ___."
    */
@@ -130,6 +135,7 @@ export const allExtractorMessageIds: Set<string> = new Set<string>([
   'ae-incompatible-release-tags',
   'ae-missing-release-tag',
   'ae-misplaced-package-tag',
+  'ae-misplaced-module-tag',
   'ae-forgotten-export',
   'ae-internal-missing-underscore',
   'ae-internal-mixed-release-tag',

apps/api-extractor/src/generators/DtsRollupGenerator.ts

@@ -23,6 +23,7 @@ import type { IAstModuleExportInfo } from '../analyzer/AstModule';
 import { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';
 import type { AstEntity } from '../analyzer/AstEntity';
 import { ModuleDocComment } from '../aedoc/ModuleDocComment';
+import { ExtractorMessageId } from '../api/ExtractorMessageId';
 
 /**
  * Used with DtsRollupGenerator.writeTypingsFile()
@@ -184,7 +185,10 @@ export class DtsRollupGenerator {
 
         // Check if the source file has a @module comment and emit it before the namespace declaration
         const sourceFile: ts.SourceFile = astEntity.astModule.sourceFile;
-        const moduleCommentRange: ts.TextRange | undefined = ModuleDocComment.tryFindInSourceFile(sourceFile);
+        const moduleCommentRange: ts.TextRange | undefined = ModuleDocComment.tryFindInSourceFile(
+          sourceFile,
+          collector
+        );
         if (moduleCommentRange) {
           const moduleComment: string = sourceFile.text.substring(
             moduleCommentRange.pos,

common/reviews/api/api-extractor.api.md

@@ -151,6 +151,7 @@ export enum ExtractorMessageId {
     IncompatibleReleaseTags = "ae-incompatible-release-tags",
     InternalMissingUnderscore = "ae-internal-missing-underscore",
     InternalMixedReleaseTag = "ae-internal-mixed-release-tag",
+    MisplacedModuleTag = "ae-misplaced-module-tag",
     MisplacedPackageTag = "ae-misplaced-package-tag",
     MissingGetter = "ae-missing-getter",
     MissingReleaseTag = "ae-missing-release-tag",