refactor(docs): Enable ts-check in API Documentation generation modules and fix typing violations (#23730)

Also exposed a couple of issues that should be addressed in
`api-markdown-documenter`.

Author: Josmithr

docs/infra/api-markdown-documenter/admonition-node.mjs

@@ -3,6 +3,9 @@
  * Licensed under the MIT License.
  */
 
+//@ts-check
+/** @typedef {import("@fluid-tools/api-markdown-documenter").DocumentationNode} DocumentationNode */
+
 import { DocumentationParentNodeBase } from "@fluid-tools/api-markdown-documenter";
 
 /**
@@ -44,7 +47,7 @@ export const admonitionNodeType = "Admonition";
  */
 export class AdmonitionNode extends DocumentationParentNodeBase {
 	/**
-	 * @param {@fluid-tools/api-markdown-documenter#DocumentationNode[]} children - Child node content.
+	 * @param {DocumentationNode[]} children - Child node content.
 	 * @param {string} admonitionKind - The kind of admonition. See {@link https://docusaurus.io/docs/markdown-features/admonitions}.
 	 * @param {string | undefined} title - (Optional) Title text for the admonition.
 	 */

docs/infra/api-markdown-documenter/api-documentation-layout.mjs

@@ -4,6 +4,8 @@
  */
 
 //@ts-check
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItem} ApiItem */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItemTransformationConfiguration} ApiItemTransformationConfiguration */
 
 import {
 	ApiItemKind,
@@ -45,7 +47,7 @@ const supportDocsLinkSpan = new SpanNode([
  * If we later wish to differentiate between release tags of `@legacy` items, this function will need
  * to be updated.
  *
- * @param apiItem {import("@fluid-tools/api-markdown-documenter").ApiItem} - The API item for which the import notice is being created.
+ * @param {ApiItem} apiItem - The API item for which the import notice is being created.
  */
 function createImportNotice(apiItem) {
 	const containingPackage = apiItem.getAssociatedPackage();
@@ -105,7 +107,7 @@ function createImportNotice(apiItem) {
  *
  * If the item is tagged as "@system", displays an internal notice with use notes.
  *
- * @param apiItem {import("@fluid-tools/api-markdown-documenter").ApiItem} - The API item for which the system notice is being created.
+ * @param {ApiItem} apiItem - The API item for which the system notice is being created.
  */
 function createSystemNotice(apiItem) {
 	if (ApiItemUtilities.ancestryHasModifierTag(apiItem, "@system")) {
@@ -144,9 +146,9 @@ function createSystemNotice(apiItem) {
  *
  * 1. See (if any)
  *
- * @param {import("@fluid-tools/api-markdown-documenter").ApiItem} apiItem - The API item being rendered.
- * @param {import("@fluid-tools/api-markdown-documenter").SectionNode[] | undefined} itemSpecificContent - API item-specific details to be included in the default layout.
- * @param {import("@fluid-tools/api-markdown-documenter").ApiItemTransformationConfiguration} config - Transformation configuration.
+ * @param {ApiItem} apiItem - The API item being rendered.
+ * @param {SectionNode[] | undefined} itemSpecificContent - API item-specific details to be included in the default layout.
+ * @param {ApiItemTransformationConfiguration} config - Transformation configuration.
  *
  * @returns An array of sections describing the layout. See {@link @fluid-tools/api-markdown-documenter#ApiItemTransformationConfiguration.createDefaultLayout}.
  */
@@ -245,8 +247,8 @@ export function layoutContent(apiItem, itemSpecificContent, config) {
  *
  * @remarks Displayed as a Docusaurus admonition. See {@link AdmonitionNode} and {@link renderAdmonitionNode}.
  *
- * @param {import("@fluid-tools/api-markdown-documenter").ApiItem} apiItem - The API item being rendered.
- * @param {import("@fluid-tools/api-markdown-documenter").ApiItemTransformationConfiguration} config - Transformation configuration.
+ * @param {ApiItem} apiItem - The API item being rendered.
+ * @param {ApiItemTransformationConfiguration} config - Transformation configuration.
  *
  * @returns The doc section if the API item had a `@remarks` comment, otherwise `undefined`.
  */
@@ -257,6 +259,9 @@ function createDeprecationNoticeSection(apiItem, config) {
 	}
 
 	const transformedDeprecatedBlock = transformTsdocNode(deprecatedBlock, apiItem, config);
+	if (transformedDeprecatedBlock === undefined) {
+		throw new Error("Failed to transform deprecated block.");
+	}
 
 	return new AdmonitionNode(
 		[transformedDeprecatedBlock],

docs/infra/api-markdown-documenter/custom-renderers.mjs

@@ -3,17 +3,25 @@
  * Licensed under the MIT License.
  */
 
+//@ts-check
+/** @typedef {import("@fluid-tools/api-markdown-documenter").DocumentationNode} DocumentationNode */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").MarkdownRenderContext} MarkdownRenderContext */
+
 import {
+	BlockQuoteNode,
 	documentationNodeToHtml,
+	DocumentWriter,
 	HtmlRenderer,
 	MarkdownRenderer,
+	TableNode,
 } from "@fluid-tools/api-markdown-documenter";
+import { AdmonitionNode } from "./admonition-node.mjs";
 
 /**
  * Renders a Docusaurus Admonition from the given parameters.
  * @param {string} admonitionKind -
  * @param {string | undefined} title
- * @param {object[]} children - Child contents to render in the admonition body.
+ * @param {DocumentationNode[]} children - Child contents to render in the admonition body.
  * @param {DocumentWriter} writer - Writer context object into which the document contents will be written.
  * @param {MarkdownRenderContext} context - See {@link @fluid-tools/api-markdown-documenter#MarkdownRenderContext}.
  */
@@ -59,6 +67,15 @@ export function renderBlockQuoteNode(blockQuoteNode, writer, context) {
 	renderAdmonition("note", undefined, blockQuoteNode.children, writer, context);
 }
 
+/**
+ * Type guard for element HAST nodes.
+ * @param {import("hast").Nodes} node - The node to check.
+ * @returns {node is import("hast").Element} Whether the node is an element.
+ */
+function isElement(node) {
+	return node.type === "element";
+}
+
 /**
  * Renders a {@link TableNode} using HTML syntax, and applies the desired CSS class to it.
  *
@@ -68,11 +85,18 @@ export function renderBlockQuoteNode(blockQuoteNode, writer, context) {
  */
 export function renderTableNode(tableNode, writer, context) {
 	// Generate HTML AST for the table node.
+
 	const htmlTree = documentationNodeToHtml(tableNode, {
 		rootFormatting: context,
 		startingHeadingLevel: context.headingLevel,
+		// @ts-ignore TODO: Fix this in the API-Markdown-Documenter package
 		logger: context.logger,
 	});
+
+	if (!isElement(htmlTree)) {
+		throw new Error("Expected an HTML element as output from table node transformation.");
+	}
+
 	htmlTree.properties.class = "table table-striped table-hover";
 
 	// Convert the HTML AST to a string.

docs/infra/api-markdown-documenter/render-api-documentation.mjs

@@ -3,6 +3,11 @@
  * Licensed under the MIT License.
  */
 
+//@ts-check
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItem} ApiItem */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItemTransformationConfiguration} ApiItemTransformationConfiguration */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ApiPackage} ApiPackage */
+
 import {
 	ApiItemKind,
 	ApiItemUtilities,
@@ -31,8 +36,19 @@ import {
 const generatedContentNotice =
 	"<!-- Do not edit this file. It is automatically generated by @fluidtools/api-markdown-documenter. -->";
 
+/**
+ * Type guard for identifying a package API item.
+ *
+ * @param {ApiItem} apiItem - The API item being type-checked.
+ * @returns {apiItem is ApiPackage} Whether the API item is a package.
+ */
+function isPackage(apiItem) {
+	return apiItem.kind === ApiItemKind.Package;
+}
+
 /**
  * Generates a documentation suite for the API model saved under `inputDir`, saving the output to `outputDir`.
+ *
  * @param {string} inputDir - The directory path containing the API model to be processed.
  * @param {string} outputDir - The directory path under which the generated documentation suite will be saved.
  * @param {string} uriRootDir - The base for all links between API members.
@@ -43,6 +59,7 @@ const generatedContentNotice =
 export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, apiVersion) {
 	/**
 	 * Logs a progress message, prefaced with the API version number to help differentiate parallel logging output.
+	 * @param {string} message - The progress message to log.
 	 */
 	function logProgress(message) {
 		console.log(`(v${apiVersion}) ${message}`);
@@ -51,6 +68,11 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 	/**
 	 * Logs the error with the specified message, prefaced with the API version number to help differentiate parallel
 	 * logging output, and re-throws the error.
+	 *
+	 * @param {string} message - The progress message to log.
+	 * @param {unknown} error - The error to log and re-throw.
+	 *
+	 * @returns {never} This function always throws an error.
 	 */
 	function logErrorAndRethrow(message, error) {
 		console.error(chalk.red(`(v${apiVersion}) ${message}:`));
@@ -70,10 +92,16 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 
 	const apiModel = await loadModel({ modelDirectoryPath: inputDir });
 
-	// Custom renderers that utilize Docusaurus syntax for certain kinds of documentation elements.
+	/**
+	 * Custom renderers that utilize Docusaurus syntax for certain kinds of documentation elements.
+	 * @type {import("@fluid-tools/api-markdown-documenter").MarkdownRenderers}
+	 */
 	const customRenderers = {
+		// @ts-ignore TODO: fix typing in API-Markdown-Documenter package
 		[DocumentationNodeType.BlockQuote]: renderBlockQuoteNode,
+		// @ts-ignore TODO: fix typing in API-Markdown-Documenter package
 		[DocumentationNodeType.Table]: renderTableNode,
+		// @ts-ignore TODO: fix typing in API-Markdown-Documenter package
 		[admonitionNodeType]: renderAdmonitionNode,
 	};
 
@@ -115,7 +143,6 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 				}
 			},
 		},
-		newlineKind: "lf",
 		uriRoot: uriRootDir,
 		includeBreadcrumb: false, // Docusaurus includes this by default based on file hierarchy
 		includeTopLevelDocumentHeading: false, // We inject `title` front-matter metadata instead
@@ -146,7 +173,7 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 		},
 		exclude: (apiItem) => {
 			// Exclude packages that aren't intended for public consumption.
-			if (apiItem.kind === ApiItemKind.Package) {
+			if (isPackage(apiItem)) {
 				const packageName = apiItem.name;
 				const packageScope = PackageName.getScope(packageName);
 
@@ -181,6 +208,9 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 	await Promise.all(
 		documents.map(async (document) => {
 			const documentApiItem = document.apiItem;
+			if (documentApiItem === undefined) {
+				throw new Error("Document does not have an associated API item.");
+			}
 
 			// #region Filter documents based on site-specific requirements
 
@@ -225,14 +255,22 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 				await fs.writeFile(filePath, fileContents);
 			} catch (error) {
 				logErrorAndRethrow(
-					`Encountered error while writing file output for "${document.apiItem.displayName}"`,
+					`Encountered error while writing file output for "${documentApiItem.displayName}"`,
 					error,
 				);
 			}
 		}),
 	);
 }
 
+/**
+ * Generate `yaml`-formatted front-matter for the API item. For use by Docusaurus.
+ *
+ * @param {ApiItem} documentApiItem - The item for which front-matter is being generated.
+ * @param {ApiItemTransformationConfiguration} config - The transformation configuration.
+ *
+ * @returns {string} The front-matter, formatted as a string.
+ */
 function createFrontMatter(documentApiItem, config) {
 	let title, sidebarLabel;
 	if (documentApiItem.kind === ApiItemKind.Model) {

docs/package.json

@@ -77,6 +77,8 @@
 		"@microsoft/applicationinsights-web": "^3.3.4",
 		"@playwright/test": "^1.49.0",
 		"@rushstack/node-core-library": "^5.9.0",
+		"@types/fs-extra": "^11.0.4",
+		"@types/hast": "^3.0.4",
 		"@types/node": "^22.9.1",
 		"@wayneferrao/docusaurus-search-local": "^0.48.5",
 		"chalk": "^5.3.0",