improvement(build-tools): preserve @packageDocumentation with `gene…

…rate entrypoints` (microsoft#21762)

Copy `@packageDocumentation` comment found in entrypoint to conform with
api-extractor expectations.

Comment is not copied to Node10 compat files.

[AB#8516](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/8516)

build-tools/packages/build-cli/src/library/commands/generateEntrypoints.ts

@@ -18,7 +18,7 @@ import { ApiLevel } from "../apiLevel.js";
 import { ApiTag } from "../apiTag.js";
 import type { ExportData, Node10CompatExportData } from "../packageExports.js";
 import { queryTypesResolutionPathsFromPackageExports } from "../packageExports.js";
-import { getApiExports } from "../typescriptApi.js";
+import { getApiExports, getPackageDocumentationText } from "../typescriptApi.js";
 
 import { unscopedPackageNameString } from "./constants.js";
 
@@ -362,6 +362,9 @@ async function generateEntrypoints(
 	const mainSourceFile = project.addSourceFileAtPath(mainEntrypoint);
 	const exports = getApiExports(mainSourceFile);
 
+	const packageDocumentationHeader = getPackageDocumentationText(mainSourceFile);
+	const newFileHeader = `${generatedHeader}${packageDocumentationHeader}`;
+
 	// This order is critical as alpha should include beta should include public.
 	// Legacy is separate and should not be included in any other level. But it
 	// may include public.
@@ -437,7 +440,7 @@ async function generateEntrypoints(
 		// Avoid adding export declaration unless there are exports.
 		// Adding one without any named exports results in a * export (everything).
 		if (namedExports.length > 0) {
-			sourceFile.insertText(0, generatedHeader);
+			sourceFile.insertText(0, newFileHeader);
 			sourceFile.addExportDeclaration({
 				leadingTrivia: "\n",
 				moduleSpecifier: `./${mainSourceFile
@@ -449,7 +452,7 @@ async function generateEntrypoints(
 			// At this point we already know that package "export" has a request
 			// for this entrypoint. Warn of emptiness, but make it valid for use.
 			log.warning(`no exports for ${outFile} using API level tag ${apiTagLevel}`);
-			sourceFile.insertText(0, `${generatedHeader}export {}\n\n`);
+			sourceFile.insertText(0, `${newFileHeader}export {}\n\n`);
 		}
 
 		fileSavePromises.push(sourceFile.save());

build-tools/packages/build-cli/src/library/typescriptApi.ts

@@ -232,3 +232,30 @@ export function getApiExports(sourceFile: SourceFile): ExportRecords {
 
 	return records;
 }
+
+/**
+ * Searches given source file for the package documentation (first
+ * `@packageDocumentation` tagged comment).
+ *
+ * @returns Found full text of the package documentation or empty string.
+ *
+ * @privateRemarks
+ * If we find trouble with practical extraction, consider replicating api-extractor's logic at:
+ * {@link https://github.com/microsoft/rushstack/blob/main/apps/api-extractor/src/aedoc/PackageDocComment.ts}
+ *
+ * Here a simplified approach is taken leveraging ts-morph's comment organization.
+ */
+export function getPackageDocumentationText(sourceFile: SourceFile): string {
+	const statements = sourceFile.getStatementsWithComments();
+	for (const statement of statements) {
+		const comments = statement.getLeadingCommentRanges();
+		for (const comment of comments) {
+			const jsDoc = comment.getText();
+			if (jsDoc.includes("@packageDocumentation")) {
+				return jsDoc;
+			}
+		}
+	}
+
+	return "";
+}