@savvy-web/rslib-builder 0.1.1 → 0.2.0

package/index.js

@@ -8,6 +8,7 @@ import { getWorkspaceRoot } from "workspace-tools";
 import { logger as core_logger } from "@rsbuild/core";
 import picocolors from "picocolors";
 import { spawn } from "node:child_process";
+import { StandardTags, Standardization, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
 import { createCompilerHost, findConfigFile, formatDiagnostic, parseJsonConfigFileContent, readConfigFile, sys } from "typescript";
 import { createRequire } from "node:module";
 import { inspect } from "node:util";
@@ -394,6 +395,101 @@ const TSConfigs = {
         }
     }
 };
+class TsDocConfigBuilder {
+    static ALL_GROUPS = [
+        "core",
+        "extended",
+        "discretionary"
+    ];
+    static GROUP_TO_STANDARDIZATION = {
+        core: Standardization.Core,
+        extended: Standardization.Extended,
+        discretionary: Standardization.Discretionary
+    };
+    static TAG_GROUPS = {
+        get core () {
+            return TsDocConfigBuilder.getTagsForGroup("core");
+        },
+        get extended () {
+            return TsDocConfigBuilder.getTagsForGroup("extended");
+        },
+        get discretionary () {
+            return TsDocConfigBuilder.getTagsForGroup("discretionary");
+        }
+    };
+    static isCI() {
+        return "true" === process.env.CI || "true" === process.env.GITHUB_ACTIONS;
+    }
+    static getTagsForGroup(group) {
+        const standardization = TsDocConfigBuilder.GROUP_TO_STANDARDIZATION[group];
+        return StandardTags.allDefinitions.filter((tag)=>tag.standardization === standardization).map((tag)=>({
+                tagName: tag.tagName,
+                syntaxKind: TsDocConfigBuilder.syntaxKindToString(tag.syntaxKind),
+                ...tag.allowMultiple ? {
+                    allowMultiple: true
+                } : {}
+            }));
+    }
+    static shouldPersist(persistConfig) {
+        if (false === persistConfig) return false;
+        if (void 0 !== persistConfig) return true;
+        return !TsDocConfigBuilder.isCI();
+    }
+    static getConfigPath(persistConfig, cwd) {
+        if ("string" == typeof persistConfig) return (0, external_node_path_.isAbsolute)(persistConfig) ? persistConfig : (0, external_node_path_.join)(cwd, persistConfig);
+        if (persistConfig instanceof URL || Buffer.isBuffer(persistConfig)) {
+            const pathStr = persistConfig.toString();
+            return (0, external_node_path_.isAbsolute)(pathStr) ? pathStr : (0, external_node_path_.join)(cwd, pathStr);
+        }
+        return (0, external_node_path_.join)(cwd, "tsdoc.json");
+    }
+    static build(options = {}) {
+        const groups = options.groups ?? TsDocConfigBuilder.ALL_GROUPS;
+        const allGroupsEnabled = TsDocConfigBuilder.ALL_GROUPS.every((g)=>groups.includes(g));
+        const tagDefinitions = [];
+        const supportForTags = {};
+        for (const group of groups)for (const tag of TsDocConfigBuilder.TAG_GROUPS[group]){
+            supportForTags[tag.tagName] = true;
+            if (!allGroupsEnabled) tagDefinitions.push(tag);
+        }
+        if (options.tagDefinitions) for (const tag of options.tagDefinitions){
+            tagDefinitions.push(tag);
+            supportForTags[tag.tagName] = true;
+        }
+        if (options.supportForTags) Object.assign(supportForTags, options.supportForTags);
+        return {
+            tagDefinitions,
+            supportForTags,
+            useStandardTags: allGroupsEnabled
+        };
+    }
+    static async writeConfigFile(options = {}, outputDir) {
+        const { tagDefinitions, supportForTags, useStandardTags } = TsDocConfigBuilder.build(options);
+        const tsdocConfig = {
+            $schema: "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+            noStandardTags: !useStandardTags,
+            reportUnsupportedHtmlElements: false
+        };
+        if (tagDefinitions.length > 0) tsdocConfig.tagDefinitions = tagDefinitions;
+        if (Object.keys(supportForTags).length > 0) tsdocConfig.supportForTags = supportForTags;
+        const configPath = (0, external_node_path_.join)(outputDir, "tsdoc.json");
+        await writeFile(configPath, JSON.stringify(tsdocConfig, null, 2));
+        return configPath;
+    }
+    static syntaxKindToString(kind) {
+        switch(kind){
+            case TSDocTagSyntaxKind.InlineTag:
+                return "inline";
+            case TSDocTagSyntaxKind.BlockTag:
+                return "block";
+            case TSDocTagSyntaxKind.ModifierTag:
+                return "modifier";
+        }
+    }
+}
+function getUnscopedPackageName(name) {
+    return name.startsWith("@") ? name.split("/")[1] ?? name : name;
+}
 function getTsgoBinPath() {
     const cwd = process.cwd();
     const localTsgoBin = (0, external_node_path_.join)(cwd, "node_modules", ".bin", "tsgo");
@@ -445,9 +541,25 @@ async function bundleDtsFiles(options) {
     const { cwd, tempDtsDir, tempOutputDir, tsconfigPath, bundledPackages, entryPoints, banner, footer, apiModel } = options;
     const bundledFiles = new Map();
     let apiModelPath;
+    let tsdocMetadataPath;
     const apiModelEnabled = true === apiModel || "object" == typeof apiModel && (void 0 === apiModel.enabled || true === apiModel.enabled);
-    const apiModelFilename = "object" == typeof apiModel && apiModel.filename ? apiModel.filename : "api.model.json";
+    const apiModelFilename = "object" == typeof apiModel && apiModel.filename ? apiModel.filename : "api.json";
+    const tsdocOptions = "object" == typeof apiModel ? apiModel.tsdoc : void 0;
+    const tsdocMetadataOption = "object" == typeof apiModel ? apiModel.tsdocMetadata : void 0;
+    const tsdocWarnings = tsdocOptions?.warnings ?? (TsDocConfigBuilder.isCI() ? "fail" : "log");
+    const tsdocMetadataEnabled = apiModelEnabled && (void 0 === tsdocMetadataOption || true === tsdocMetadataOption || "object" == typeof tsdocMetadataOption && false !== tsdocMetadataOption.enabled);
+    const tsdocMetadataFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
     getApiExtractorPath();
+    const persistConfig = tsdocOptions?.persistConfig;
+    const shouldPersist = TsDocConfigBuilder.shouldPersist(persistConfig);
+    const tsdocConfigOutputPath = TsDocConfigBuilder.getConfigPath(persistConfig, cwd);
+    let tsdocConfigPath;
+    let tsdocConfigFile;
+    if (apiModelEnabled) {
+        tsdocConfigPath = await TsDocConfigBuilder.writeConfigFile(tsdocOptions ?? {}, (0, external_node_path_.dirname)(tsdocConfigOutputPath));
+        const { TSDocConfigFile } = await import("@microsoft/tsdoc-config");
+        tsdocConfigFile = TSDocConfigFile.loadForFolder((0, external_node_path_.dirname)(tsdocConfigPath));
+    }
     const { Extractor, ExtractorConfig } = await import("@microsoft/api-extractor");
     for (const [entryName, sourcePath] of entryPoints){
         const normalizedSourcePath = sourcePath.replace(/^\.\//, "");
@@ -469,6 +581,8 @@ async function bundleDtsFiles(options) {
         const tempBundledPath = (0, external_node_path_.join)(tempOutputDir, outputFileName);
         const generateApiModel = apiModelEnabled && "index" === entryName;
         const tempApiModelPath = generateApiModel ? (0, external_node_path_.join)(tempOutputDir, apiModelFilename) : void 0;
+        const generateTsdocMetadata = tsdocMetadataEnabled && "index" === entryName;
+        const tempTsdocMetadataPath = generateTsdocMetadata ? (0, external_node_path_.join)(tempOutputDir, tsdocMetadataFilename) : void 0;
         const extractorConfig = ExtractorConfig.prepare({
             configObject: {
                 projectFolder: cwd,
@@ -484,11 +598,17 @@ async function bundleDtsFiles(options) {
                     enabled: true,
                     apiJsonFilePath: tempApiModelPath
                 } : void 0,
+                tsdocMetadata: generateTsdocMetadata ? {
+                    enabled: true,
+                    tsdocMetadataFilePath: tempTsdocMetadataPath
+                } : void 0,
                 bundledPackages: bundledPackages
             },
             packageJsonFullPath: (0, external_node_path_.join)(cwd, "package.json"),
-            configObjectFullPath: void 0
+            configObjectFullPath: void 0,
+            tsdocConfigFile: tsdocConfigFile
         });
+        const collectedTsdocWarnings = [];
         const extractorResult = Extractor.invoke(extractorConfig, {
             localBuild: true,
             showVerboseMessages: false,
@@ -497,11 +617,35 @@ async function bundleDtsFiles(options) {
                     message.logLevel = "none";
                     return;
                 }
-                if (message.text?.includes("You have changed the public API signature")) message.logLevel = "none";
+                if (message.text?.includes("You have changed the public API signature")) {
+                    message.logLevel = "none";
+                    return;
+                }
+                const isTsdocMessage = message.messageId?.startsWith("tsdoc-");
+                if (isTsdocMessage && message.text) if ("none" === tsdocWarnings) message.logLevel = "none";
+                else {
+                    collectedTsdocWarnings.push({
+                        text: message.text,
+                        sourceFilePath: message.sourceFilePath,
+                        sourceFileLine: message.sourceFileLine,
+                        sourceFileColumn: message.sourceFileColumn
+                    });
+                    message.logLevel = "none";
+                }
             }
         });
         if (!extractorResult.succeeded) throw new Error(`API Extractor failed for entry "${entryName}"`);
+        if (collectedTsdocWarnings.length > 0) {
+            const formatWarning = (warning)=>{
+                const location = warning.sourceFilePath ? `${picocolors.cyan((0, external_node_path_.relative)(cwd, warning.sourceFilePath))}${warning.sourceFileLine ? `:${warning.sourceFileLine}` : ""}${warning.sourceFileColumn ? `:${warning.sourceFileColumn}` : ""}` : null;
+                return location ? `${location}: ${picocolors.yellow(warning.text)}` : picocolors.yellow(warning.text);
+            };
+            const warningMessages = collectedTsdocWarnings.map(formatWarning).join("\n  ");
+            if ("fail" === tsdocWarnings) throw new Error(`TSDoc validation failed for entry "${entryName}":\n  ${warningMessages}`);
+            if ("log" === tsdocWarnings) core_logger.warn(`TSDoc warnings for entry "${entryName}":\n  ${warningMessages}`);
+        }
         if (generateApiModel && tempApiModelPath) apiModelPath = tempApiModelPath;
+        if (generateTsdocMetadata && tempTsdocMetadataPath) tsdocMetadataPath = tempTsdocMetadataPath;
         if (banner || footer) {
             let content = await promises_readFile(tempBundledPath, "utf-8");
             if (banner) content = `${banner}\n${content}`;
@@ -510,9 +654,16 @@ async function bundleDtsFiles(options) {
         }
         bundledFiles.set(entryName, tempBundledPath);
     }
+    let persistedTsdocConfigPath;
+    if (tsdocConfigPath) if (shouldPersist) persistedTsdocConfigPath = tsdocConfigPath;
+    else try {
+        await unlink(tsdocConfigPath);
+    } catch  {}
     return {
         bundledFiles,
-        apiModelPath
+        apiModelPath,
+        tsdocMetadataPath,
+        tsdocConfigPath: persistedTsdocConfigPath
     };
 }
 function stripSourceMapComment(content) {
@@ -719,7 +870,7 @@ function runTsgo(options) {
                             await mkdir(tempBundledDir, {
                                 recursive: true
                             });
-                            const { bundledFiles, apiModelPath } = await bundleDtsFiles({
+                            const { bundledFiles, apiModelPath, tsdocMetadataPath, tsdocConfigPath } = await bundleDtsFiles({
                                 cwd,
                                 tempDtsDir,
                                 tempOutputDir: tempBundledDir,
@@ -742,20 +893,13 @@ function runTsgo(options) {
                             }
                             core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted ${emittedCount} bundled declaration file${1 === emittedCount ? "" : "s"} through asset pipeline`);
                             if (apiModelPath) {
-                                const apiModelFilename = "object" == typeof options.apiModel && options.apiModel.filename ? options.apiModel.filename : "api.model.json";
+                                const defaultApiModelFilename = packageJson.name ? `${getUnscopedPackageName(packageJson.name)}.api.json` : "api.json";
+                                const apiModelFilename = "object" == typeof options.apiModel && options.apiModel.filename ? options.apiModel.filename : defaultApiModelFilename;
                                 const apiModelContent = await promises_readFile(apiModelPath, "utf-8");
                                 const apiModelSource = new context.sources.OriginalSource(apiModelContent, apiModelFilename);
                                 context.compilation.emitAsset(apiModelFilename, apiModelSource);
-                                if (filesArray) filesArray.add(apiModelFilename);
-                                core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted API model: ${apiModelFilename}`);
-                                const shouldAddNpmIgnore = true === options.apiModel || "object" == typeof options.apiModel && false !== options.apiModel.npmIgnore;
-                                if (shouldAddNpmIgnore) {
-                                    const npmIgnoreContent = `# Exclude API model from npm publish (used by internal tooling)\n${apiModelFilename}\n`;
-                                    const npmIgnoreSource = new context.sources.OriginalSource(npmIgnoreContent, ".npmignore");
-                                    context.compilation.emitAsset(".npmignore", npmIgnoreSource);
-                                    if (filesArray) filesArray.add(".npmignore");
-                                    core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted .npmignore to exclude ${apiModelFilename}`);
-                                }
+                                if (filesArray) filesArray.add(`!${apiModelFilename}`);
+                                core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted API model: ${apiModelFilename} (excluded from npm publish)`);
                                 const isCI = "true" === process.env.GITHUB_ACTIONS || "true" === process.env.CI;
                                 const localPaths = "object" == typeof options.apiModel ? options.apiModel.localPaths : void 0;
                                 if (localPaths && localPaths.length > 0 && !isCI) for (const localPath of localPaths){
@@ -770,6 +914,13 @@ function runTsgo(options) {
                                     });
                                     const apiModelDestPath = (0, external_node_path_.join)(resolvedPath, apiModelFilename);
                                     await writeFile(apiModelDestPath, apiModelContent, "utf-8");
+                                    if (tsdocMetadataPath) {
+                                        const tsdocMetadataOption = "object" == typeof options.apiModel ? options.apiModel.tsdocMetadata : void 0;
+                                        const localTsdocFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
+                                        const tsdocContent = await promises_readFile(tsdocMetadataPath, "utf-8");
+                                        const tsdocDestPath = (0, external_node_path_.join)(resolvedPath, localTsdocFilename);
+                                        await writeFile(tsdocDestPath, tsdocContent, "utf-8");
+                                    }
                                     const packageJsonAsset = context.compilation.assets["package.json"];
                                     if (packageJsonAsset) {
                                         const rawContent = "function" == typeof packageJsonAsset.source ? packageJsonAsset.source() : packageJsonAsset.source;
@@ -777,9 +928,26 @@ function runTsgo(options) {
                                         const packageJsonDestPath = (0, external_node_path_.join)(resolvedPath, "package.json");
                                         await writeFile(packageJsonDestPath, packageJsonContent, "utf-8");
                                     }
-                                    core_logger.info(`${picocolors.dim(`[${envId}]`)} Copied API model and package.json to: ${localPath}`);
+                                    const copiedFiles = tsdocMetadataPath ? "API model, tsdoc-metadata.json, and package.json" : "API model and package.json";
+                                    core_logger.info(`${picocolors.dim(`[${envId}]`)} Copied ${copiedFiles} to: ${localPath}`);
                                 }
                             }
+                            if (tsdocMetadataPath) {
+                                const tsdocMetadataOption = "object" == typeof options.apiModel ? options.apiModel.tsdocMetadata : void 0;
+                                const tsdocMetadataFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
+                                const tsdocMetadataContent = await promises_readFile(tsdocMetadataPath, "utf-8");
+                                const tsdocMetadataSource = new context.sources.OriginalSource(tsdocMetadataContent, tsdocMetadataFilename);
+                                context.compilation.emitAsset(tsdocMetadataFilename, tsdocMetadataSource);
+                                if (filesArray) filesArray.add(tsdocMetadataFilename);
+                                core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted TSDoc metadata: ${tsdocMetadataFilename}`);
+                            }
+                            if (tsdocConfigPath) {
+                                const tsdocConfigContent = await promises_readFile(tsdocConfigPath, "utf-8");
+                                const tsdocConfigSource = new context.sources.OriginalSource(tsdocConfigContent, "tsdoc.json");
+                                context.compilation.emitAsset("tsdoc.json", tsdocConfigSource);
+                                if (filesArray) filesArray.add("!tsdoc.json");
+                                core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted TSDoc config: tsdoc.json (excluded from npm publish)`);
+                            }
                             for (const [entryName] of bundledFiles){
                                 const bundledFileName = `${entryName}.d.ts`;
                                 const mapFileName = `${bundledFileName}.map`;
@@ -1518,4 +1686,4 @@ const PackageJsonTransformPlugin = (options = {})=>{
         });
     }
 }
-export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, NodeLibraryBuilder, PackageJsonTransformPlugin, PackageJsonTransformer, PnpmCatalog, collectDtsFiles, ensureTempDeclarationDir, findTsConfig, generateTsgoArgs, getTsgoBinPath, stripSourceMapComment };
+export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, NodeLibraryBuilder, PackageJsonTransformPlugin, PackageJsonTransformer, PnpmCatalog, TsDocConfigBuilder, collectDtsFiles, ensureTempDeclarationDir, findTsConfig, generateTsgoArgs, getTsgoBinPath, getUnscopedPackageName, stripSourceMapComment };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rslib-builder",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"private": false,
 	"description": "RSlib-based build system for Node.js libraries with automatic package.json transformation, TypeScript declaration bundling, and multi-target support",
 	"homepage": "https://github.com/savvy-web/rslib-builder",
@@ -31,6 +31,8 @@
 		"./tsconfig/node/ecma/bundleless.json": "./public/tsconfig/node/ecma/bundleless.json"
 	},
 	"dependencies": {
+		"@microsoft/tsdoc": "^0.16.0",
+		"@microsoft/tsdoc-config": "^0.18.0",
 		"@pnpm/exportable-manifest": "^1000.3.0",
 		"glob": "^13.0.0",
 		"markdownlint-cli2": "^0.20.0",
@@ -72,15 +74,15 @@
 		]
 	},
 	"files": [
-		".npmignore",
+		"!rslib-builder.api.json",
 		"LICENSE",
 		"README.md",
-		"api.model.json",
 		"index.d.ts",
 		"index.js",
 		"package.json",
 		"rslib-runtime.js",
 		"tsconfig/node/ecma/lib.json",
-		"tsconfig/root.json"
+		"tsconfig/root.json",
+		"tsdoc-metadata.json"
 	]
 }

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.55.2"
+    }
+  ]
+}

package/.npmignore

@@ -1,2 +0,0 @@
-# Exclude API model from npm publish (used by internal tooling)
-api.model.json