@savvy-web/rslib-builder 0.1.2 → 0.2.1

package/README.md

@@ -50,7 +50,7 @@ Extend the provided tsconfig for optimal settings:
 ```jsonc
 // tsconfig.json
 {
-  "extends": "@savvy-web/rslib-builder/tsconfig/node/ecma/lib.json",
+  "extends": "@savvy-web/rslib-builder/tsconfig/ecma/lib.json",
   "compilerOptions": {
     "outDir": "dist"
   }

package/index.d.ts

@@ -41,6 +41,7 @@
 
 import type { ConfigParams } from '@rslib/core';
 import type { PackageJson } from 'type-fest';
+import type { PathLike } from 'node:fs';
 import type { RawCopyPattern } from '@rspack/binding';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RslibConfig } from '@rslib/core';
@@ -90,13 +91,38 @@ export declare interface ApiModelOptions {
      * ```
      */
     localPaths?: string[];
+    /**
+     * TSDoc configuration for custom tag definitions.
+     * Passed to API Extractor for documentation processing.
+     *
+     * @remarks
+     * By default, all standard tag groups (core, extended, discretionary) are
+     * enabled. Custom tags defined in `tagDefinitions` are automatically
+     * supported. Use `supportForTags` only to disable specific tags.
+     *
+     * @example
+     * ```typescript
+     * apiModel: {
+     *   enabled: true,
+     *   tsdoc: {
+     *     tagDefinitions: [{ tagName: "@error", syntaxKind: "inline" }]
+     *   }
+     * }
+     * ```
+     */
+    tsdoc?: TsDocOptions;
+    /**
+     * Options for tsdoc-metadata.json generation.
+     * @defaultValue true (enabled when apiModel is enabled)
+     */
+    tsdocMetadata?: TsDocMetadataOptions | boolean;
 }
 
 /**
  * Plugin to read package.json and configure entry points based on exports.
  *
- * @param options - Plugin configuration options
- * @param options.exportsAsIndexes - When true, export paths create index files in nested directories
+ * @param options - Plugin configuration options with properties:
+ *   - `exportsAsIndexes`: When true, export paths create index files in nested directories
  * @public
  */
 export declare const AutoEntryPlugin: (options?: {
@@ -122,7 +148,7 @@ export declare function collectDtsFiles(dir: string, baseDir?: string): Promise<
  * Plugin to generate TypeScript declaration files using tsgo and emit them through Rslib's asset pipeline.
  *
  * @remarks
- * This plugin uses tsgo (@typescript/native-preview) for faster declaration file generation
+ * This plugin uses tsgo (`\@typescript/native-preview`) for faster declaration file generation
  * and integrates with Rslib's build system by emitting generated files as compilation assets.
  *
  * ## Features
@@ -205,7 +231,7 @@ export declare interface DtsPluginOptions {
     /**
      * Packages whose types should be bundled (inlined) into the output .d.ts files.
      * Only applies when bundle is true.
-     * Supports glob patterns (e.g., '@commitlint/*', 'type-fest')
+     * Supports glob patterns (e.g., '\@commitlint/*', 'type-fest')
      * @defaultValue []
      */
     bundledPackages?: string[];
@@ -250,7 +276,7 @@ export declare function ensureTempDeclarationDir(cwd: string, name: string): Pro
  * TypeScript source files.
  *
  * **Export Path Mapping:**
- * - Converts export keys to entry names (e.g., "./utils" -> "utils")
+ * - Converts export keys to entry names (e.g., "./utils" becomes "utils")
  * - Maps the root export "." to "index" entry
  * - Replaces path separators with hyphens for nested exports (default)
  * - When `exportsAsIndexes` is true, preserves path structure
@@ -506,7 +532,7 @@ export declare interface NodeLibraryBuilderOptions {
      * specify which packages (including transitive dependencies) should have their types bundled.
      * This is particularly useful for ensuring devDependencies are fully inlined without external imports.
      *
-     * Supports minimatch patterns (e.g., '@pnpm/**', 'picocolors')
+     * Supports minimatch patterns (e.g., '\@pnpm/**', 'picocolors')
      *
      * @example
      * ```typescript
@@ -520,10 +546,10 @@ export declare interface NodeLibraryBuilderOptions {
      * Optional callback to transform files after they're built but before the files array is finalized.
      * Useful for copying/renaming files or adding additional files to the build output.
      *
-     * @param context - Transform context containing compilation context and files set
-     * @param context.compilation - Rspack compilation object with assets
-     * @param context.filesArray - Set of files that will be included in package.json files field
-     * @param context.target - Current build target (dev/npm/jsr)
+     * @param context - Transform context with properties:
+     *   - `compilation`: Rspack compilation object with assets
+     *   - `filesArray`: Set of files that will be included in package.json files field
+     *   - `target`: Current build target (dev/npm/jsr)
      *
      * @example
      * ```typescript
@@ -603,7 +629,7 @@ export declare interface NodeLibraryBuilderOptions {
  *
  * @remarks
  * This class consolidates all package.json transformation logic including:
- * - Path transformations (src/ -> dist/, .ts -> .js)
+ * - Path transformations (src/ to dist/, .ts to .js)
  * - Export conditions generation (types, import, require)
  * - Bin field transformations
  * - PNPM catalog and workspace resolution
@@ -672,6 +698,10 @@ export declare class PackageJsonTransformer {
     /**
      * Transforms the bin field for build output.
      *
+     * @remarks
+     * TypeScript bin entries are compiled to `./bin/{command-name}.js` by RSlib.
+     * Non-TypeScript entries (shell scripts, compiled JS) are preserved as-is.
+     *
      * @param bin - The bin field from package.json
      * @returns The transformed bin field
      */
@@ -680,9 +710,9 @@ export declare class PackageJsonTransformer {
      * Performs the complete package.json transformation.
      *
      * @param packageJson - The source package.json
-     * @param context - Transform context
-     * @param context.isProduction - Whether this is a production build
-     * @param context.customTransform - Optional custom transform function
+     * @param context - Transform context with properties:
+     *   - `isProduction`: Whether this is a production build
+     *   - `customTransform`: Optional custom transform function
      * @returns The transformed package.json
      */
     transform(packageJson: PackageJson, context?: {
@@ -723,7 +753,7 @@ export declare interface PackageJsonTransformOptions {
      */
     processTSExports?: boolean;
     /**
-     * Whether to collapse index files (./foo/index.ts -> ./foo.js).
+     * Whether to collapse index files (./foo/index.ts becomes ./foo.js).
      * This is typically true for bundled builds.
      * @defaultValue false
      */
@@ -816,7 +846,7 @@ export declare class PnpmCatalog {
      * @param dir - The directory containing the package (defaults to cwd)
      * @returns The resolved package.json
      *
-     * @throws {Error} When resolution fails for critical dependencies
+     * @throws When resolution fails for critical dependencies
      */
     resolvePackageJson(packageJson: PackageJson, dir?: string): Promise<PackageJson>;
     /**
@@ -859,4 +889,203 @@ export declare type TransformPackageJsonFn = (context: {
     pkg: PackageJson;
 }) => PackageJson;
 
+/**
+ * Builder for TSDoc configuration files.
+ * Handles tag group expansion, config generation, and file persistence.
+ * @public
+ */
+export declare class TsDocConfigBuilder {
+    /** All available TSDoc tag groups. */
+    static readonly ALL_GROUPS: TsDocTagGroup[];
+    /** Maps group names to TSDoc Standardization enum values. */
+    private static readonly GROUP_TO_STANDARDIZATION;
+    /**
+     * Standard TSDoc tag definitions organized by standardization group.
+     * Lazily computed from `\@microsoft/tsdoc` StandardTags.
+     */
+    static readonly TAG_GROUPS: Record<TsDocTagGroup, TsDocTagDefinition[]>;
+    /**
+     * Detects if running in a CI environment.
+     * @returns true if CI or GITHUB_ACTIONS environment variable is "true"
+     */
+    static isCI(): boolean;
+    /**
+     * Gets standard TSDoc tag definitions for a specific group.
+     * Uses StandardTags from `\@microsoft/tsdoc` package.
+     */
+    static getTagsForGroup(group: TsDocTagGroup): TsDocTagDefinition[];
+    /**
+     * Determines if the TSDoc config should be persisted to disk.
+     * @param persistConfig - The persistConfig option value
+     * @returns true if the config should be persisted
+     */
+    static shouldPersist(persistConfig: boolean | PathLike | undefined): boolean;
+    /**
+     * Gets the output path for the tsdoc.json file.
+     * @param persistConfig - The persistConfig option value
+     * @param cwd - The current working directory
+     * @returns The absolute path where tsdoc.json should be written
+     */
+    static getConfigPath(persistConfig: boolean | PathLike | undefined, cwd: string): string;
+    /**
+     * Builds the complete TSDoc configuration from options.
+     *
+     * @remarks
+     * When all groups are enabled (default), returns `useStandardTags: true` to signal
+     * that the generated config should use `noStandardTags: false` and let TSDoc
+     * automatically load all standard tags. However, `supportForTags` is still populated
+     * because API Extractor requires explicit support declarations for each tag.
+     *
+     * When a subset of groups is specified, returns `useStandardTags: false` to signal
+     * that we must explicitly define which tags to include via `noStandardTags: true`.
+     */
+    static build(options?: TsDocOptions): {
+        tagDefinitions: TsDocTagDefinition[];
+        supportForTags: Record<string, boolean>;
+        useStandardTags: boolean;
+    };
+    /**
+     * Generates a tsdoc.json file from options.
+     *
+     * @remarks
+     * When all groups are enabled (default), generates a minimal config with
+     * `noStandardTags: false` so TSDoc automatically loads all standard tags.
+     * Only custom tags need to be defined in this case.
+     *
+     * When a subset of groups is specified, generates a config with
+     * `noStandardTags: true` and explicitly defines only the tags from
+     * the enabled groups.
+     */
+    static writeConfigFile(options: TsDocOptions | undefined, outputDir: string): Promise<string>;
+    /** Converts TSDocTagSyntaxKind enum to string format. */
+    private static syntaxKindToString;
+}
+
+/**
+ * Options for tsdoc-metadata.json generation.
+ * @public
+ */
+export declare interface TsDocMetadataOptions {
+    /**
+     * Whether to generate tsdoc-metadata.json.
+     * @defaultValue true (when apiModel is enabled)
+     */
+    enabled?: boolean;
+    /**
+     * Custom filename for the TSDoc metadata file.
+     * @defaultValue "tsdoc-metadata.json"
+     */
+    filename?: string;
+}
+
+/**
+ * TSDoc configuration options for API Extractor.
+ * @remarks
+ * Provides ergonomic defaults - standard tags are auto-enabled via `groups`,
+ * custom tags are auto-supported, and `supportForTags` is only needed to
+ * disable specific tags.
+ *
+ * **Config optimization:** When all groups are enabled (default), the generated
+ * `tsdoc.json` uses `noStandardTags: false` to let TSDoc automatically load
+ * all standard tags, producing a minimal config file. When a subset of groups
+ * is specified, `noStandardTags: true` is used and only the enabled groups'
+ * tags are explicitly defined.
+ *
+ * @public
+ */
+export declare interface TsDocOptions {
+    /**
+     * TSDoc tag groups to enable. Each group includes predefined standard tags
+     * from the official `\@microsoft/tsdoc` package.
+     * - "core": Essential TSDoc tags (\@param, \@returns, \@remarks, \@deprecated, etc.)
+     * - "extended": Additional tags (\@example, \@defaultValue, \@see, \@throws, etc.)
+     * - "discretionary": Release stage tags (\@alpha, \@beta, \@public, \@internal)
+     *
+     * @remarks
+     * When all groups are enabled (the default), the generated config uses
+     * `noStandardTags: false` and TSDoc loads standard tags automatically.
+     * When a subset is specified, `noStandardTags: true` is used and only
+     * the tags from enabled groups are defined.
+     *
+     * @defaultValue ["core", "extended", "discretionary"]
+     */
+    groups?: TsDocTagGroup[];
+    /**
+     * Custom TSDoc tag definitions beyond the standard groups.
+     * These are automatically added to supportForTags (no need to declare twice).
+     *
+     * @example
+     * ```typescript
+     * tagDefinitions: [
+     *   { tagName: "@error", syntaxKind: "inline" },
+     *   { tagName: "@category", syntaxKind: "block", allowMultiple: false }
+     * ]
+     * ```
+     */
+    tagDefinitions?: TsDocTagDefinition[];
+    /**
+     * Override support for specific tags. Only needed to DISABLE tags.
+     * Tags from enabled groups and custom tagDefinitions are auto-supported.
+     *
+     * @example
+     * ```typescript
+     * // Disable @beta even though "extended" group is enabled
+     * supportForTags: { "@beta": false }
+     * ```
+     */
+    supportForTags?: Record<string, boolean>;
+    /**
+     * Persist tsdoc.json to disk for tool integration (ESLint, IDEs).
+     * - `true`: Write to project root as "tsdoc.json"
+     * - `PathLike`: Write to specified path
+     * - `false`: Clean up after API Extractor
+     *
+     * @defaultValue `true` when `CI` and `GITHUB_ACTIONS` env vars are not "true",
+     *               `false` otherwise (CI environments)
+     */
+    persistConfig?: boolean | PathLike;
+    /**
+     * How to handle TSDoc validation warnings from API Extractor.
+     * - `"log"`: Show warnings in the console but continue the build
+     * - `"fail"`: Show warnings and fail the build if any are found
+     * - `"none"`: Suppress TSDoc warnings entirely
+     *
+     * @remarks
+     * TSDoc warnings include unknown tags, malformed syntax, and other
+     * documentation issues detected by API Extractor during processing.
+     *
+     * @example
+     * ```typescript
+     * // Fail build on any TSDoc issues (CI default)
+     * warnings: "fail"
+     *
+     * // Show warnings but continue build (local default)
+     * warnings: "log"
+     * ```
+     *
+     * @defaultValue `"fail"` in CI environments (`CI` or `GITHUB_ACTIONS` env vars),
+     *               `"log"` otherwise
+     */
+    warnings?: "log" | "fail" | "none";
+}
+
+/**
+ * TSDoc tag definition for custom documentation tags.
+ * @public
+ */
+export declare interface TsDocTagDefinition {
+    /** The tag name including the at-sign prefix (e.g., `\@error`, `\@category`) */
+    tagName: string;
+    /** How the tag is parsed: "block" | "inline" | "modifier" */
+    syntaxKind: "block" | "inline" | "modifier";
+    /** Whether the tag can appear multiple times on a declaration */
+    allowMultiple?: boolean;
+}
+
+/**
+ * TSDoc standardization groups for predefined tag sets.
+ * @public
+ */
+export declare type TsDocTagGroup = "core" | "extended" | "discretionary";
+
 export { }

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";
@@ -268,7 +269,7 @@ var root_namespaceObject = JSON.parse('{"$schema":"https://json.schemastore.org/
 const requireCJS = createRequire(import.meta.url);
 const jsonImports = new Map([
     [
-        (0, external_node_path_.join)(import.meta.dirname, "../public/tsconfig/node/ecma/lib.json"),
+        (0, external_node_path_.join)(import.meta.dirname, "../public/tsconfig/ecma/lib.json"),
         lib_namespaceObject
     ],
     [
@@ -385,7 +386,7 @@ class LibraryTSConfigFile extends TSConfigFile {
     }
 }
 const Root = new TSConfigFile("Root configuration for workspace setup", (0, external_node_path_.join)(import.meta.dirname, "../public/tsconfig/root.json"));
-const NodeEcmaLib = new LibraryTSConfigFile("ECMAScript library build configuration", (0, external_node_path_.join)(import.meta.dirname, "../public/tsconfig/node/ecma/lib.json"));
+const NodeEcmaLib = new LibraryTSConfigFile("ECMAScript library build configuration", (0, external_node_path_.join)(import.meta.dirname, "../public/tsconfig/ecma/lib.json"));
 const TSConfigs = {
     root: Root,
     node: {
@@ -394,6 +395,98 @@ 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;
 }
@@ -448,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.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(/^\.\//, "");
@@ -472,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,
@@ -487,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,
@@ -500,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}`;
@@ -513,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) {
@@ -722,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,
@@ -752,30 +900,37 @@ function runTsgo(options) {
                                 context.compilation.emitAsset(apiModelFilename, apiModelSource);
                                 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){
-                                    const resolvedPath = (0, external_node_path_.join)(cwd, localPath);
-                                    const parentDir = (0, external_node_path_.dirname)(resolvedPath);
-                                    if (!existsSync(parentDir)) {
-                                        core_logger.warn(`${picocolors.dim(`[${envId}]`)} Skipping local path: parent directory does not exist: ${parentDir}`);
-                                        continue;
-                                    }
-                                    await mkdir(resolvedPath, {
-                                        recursive: true
+                                const isCI = "true" === process.env.GITHUB_ACTIONS || "true" === process.env.CI;
+                                if (localPaths && localPaths.length > 0 && !isCI) {
+                                    const tsdocMetadataOption = "object" == typeof options.apiModel ? options.apiModel.tsdocMetadata : void 0;
+                                    const localTsdocFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
+                                    api.expose("dts-local-paths-data", {
+                                        localPaths,
+                                        apiModelFilename,
+                                        localTsdocFilename,
+                                        hasTsdocMetadata: !!tsdocMetadataPath,
+                                        cwd,
+                                        distPath: `dist/${envId}`
                                     });
-                                    const apiModelDestPath = (0, external_node_path_.join)(resolvedPath, apiModelFilename);
-                                    await writeFile(apiModelDestPath, apiModelContent, "utf-8");
-                                    const packageJsonAsset = context.compilation.assets["package.json"];
-                                    if (packageJsonAsset) {
-                                        const rawContent = "function" == typeof packageJsonAsset.source ? packageJsonAsset.source() : packageJsonAsset.source;
-                                        const packageJsonContent = "string" == typeof rawContent ? rawContent : rawContent instanceof Buffer ? rawContent.toString("utf-8") : String(rawContent);
-                                        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}`);
                                 }
                             }
+                            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`;
@@ -830,6 +985,50 @@ function runTsgo(options) {
                 } else if (assetName.endsWith(".d.ts.map")) assetsToDelete.push(assetName);
                 for (const assetName of assetsToDelete)delete compiler.compilation.assets[assetName];
             });
+            api.onCloseBuild(async ()=>{
+                const localPathsData = api.useExposed("dts-local-paths-data");
+                if (!localPathsData) return;
+                const { localPaths, apiModelFilename, localTsdocFilename, hasTsdocMetadata, cwd, distPath } = localPathsData;
+                const distDir = (0, external_node_path_.join)(cwd, distPath);
+                for (const localPath of localPaths){
+                    const resolvedPath = (0, external_node_path_.join)(cwd, localPath);
+                    const parentDir = (0, external_node_path_.dirname)(resolvedPath);
+                    if (!existsSync(parentDir)) {
+                        core_logger.warn(`Skipping local path: parent directory does not exist: ${parentDir}`);
+                        continue;
+                    }
+                    const filesToCopy = [];
+                    const apiModelSrc = (0, external_node_path_.join)(distDir, apiModelFilename);
+                    if (existsSync(apiModelSrc)) filesToCopy.push({
+                        src: apiModelSrc,
+                        dest: (0, external_node_path_.join)(resolvedPath, apiModelFilename),
+                        name: apiModelFilename
+                    });
+                    if (hasTsdocMetadata) {
+                        const tsdocSrc = (0, external_node_path_.join)(distDir, localTsdocFilename);
+                        if (existsSync(tsdocSrc)) filesToCopy.push({
+                            src: tsdocSrc,
+                            dest: (0, external_node_path_.join)(resolvedPath, localTsdocFilename),
+                            name: localTsdocFilename
+                        });
+                    }
+                    const packageJsonSrc = (0, external_node_path_.join)(distDir, "package.json");
+                    if (existsSync(packageJsonSrc)) filesToCopy.push({
+                        src: packageJsonSrc,
+                        dest: (0, external_node_path_.join)(resolvedPath, "package.json"),
+                        name: "package.json"
+                    });
+                    await mkdir(resolvedPath, {
+                        recursive: true
+                    });
+                    for (const file of filesToCopy){
+                        const content = await promises_readFile(file.src, "utf-8");
+                        await writeFile(file.dest, content, "utf-8");
+                    }
+                    const fileNames = filesToCopy.map((f)=>f.name).join(", ");
+                    core_logger.info(`Copied ${fileNames} to: ${localPath}`);
+                }
+            });
         }
     };
 };
@@ -1115,9 +1314,9 @@ class PackageJsonTransformer {
     }
     transformExportPath(path) {
         let transformedPath = path;
+        if (transformedPath.startsWith("./src/")) transformedPath = `./${transformedPath.slice(6)}`;
         if (transformedPath.startsWith("./exports/")) transformedPath = `./${transformedPath.slice(10)}`;
-        else if (transformedPath.startsWith("./public/")) transformedPath = `./${transformedPath.slice(9)}`;
-        else if (transformedPath.startsWith("./src/")) transformedPath = `./${transformedPath.slice(6)}`;
+        if (transformedPath.startsWith("./public/")) transformedPath = `./${transformedPath.slice(9)}`;
         if (this.options.processTSExports) {
             const { collapseIndex } = this.options;
             if (collapseIndex && transformedPath.endsWith("/index.ts") && "./index.ts" !== transformedPath) transformedPath = `${transformedPath.slice(0, -9)}.js`;
@@ -1143,10 +1342,14 @@ class PackageJsonTransformer {
         return exports;
     }
     transformBin(bin) {
-        if ("string" == typeof bin) return this.transformExportPath(bin);
+        if ("string" == typeof bin) {
+            if (bin.endsWith(".ts") || bin.endsWith(".tsx")) return "./bin/cli.js";
+            return bin;
+        }
         if (bin && "object" == typeof bin) {
             const transformed = {};
-            for (const [command, path] of Object.entries(bin))if (void 0 !== path) transformed[command] = this.transformExportPath(path);
+            for (const [command, path] of Object.entries(bin))if (void 0 !== path) if (path.endsWith(".ts") || path.endsWith(".tsx")) transformed[command] = `./bin/${command}.js`;
+            else transformed[command] = path;
             return transformed;
         }
         return bin;
@@ -1228,9 +1431,9 @@ class PackageJsonTransformer {
 }
 function transformExportPath(path, processTSExports = true, collapseIndex = false) {
     let transformedPath = path;
+    if (transformedPath.startsWith("./src/")) transformedPath = `./${transformedPath.slice(6)}`;
     if (transformedPath.startsWith("./exports/")) transformedPath = `./${transformedPath.slice(10)}`;
-    else if (transformedPath.startsWith("./public/")) transformedPath = `./${transformedPath.slice(9)}`;
-    else if (transformedPath.startsWith("./src/")) transformedPath = `./${transformedPath.slice(6)}`;
+    if (transformedPath.startsWith("./public/")) transformedPath = `./${transformedPath.slice(9)}`;
     if (processTSExports) {
         if (collapseIndex && transformedPath.endsWith("/index.ts") && "./index.ts" !== transformedPath) transformedPath = `${transformedPath.slice(0, -9)}.js`;
         else if (collapseIndex && transformedPath.endsWith("/index.tsx") && "./index.tsx" !== transformedPath) transformedPath = `${transformedPath.slice(0, -10)}.js`;
@@ -1244,11 +1447,15 @@ function createTypePath(jsPath, collapseIndex = true) {
     if (jsPath.endsWith(".js")) return `${jsPath.slice(0, -3)}.d.ts`;
     return `${jsPath}.d.ts`;
 }
-function transformPackageBin(bin, processTSExports = true) {
-    if ("string" == typeof bin) return transformExportPath(bin, processTSExports);
+function transformPackageBin(bin, _processTSExports = true) {
+    if ("string" == typeof bin) {
+        if (bin.endsWith(".ts") || bin.endsWith(".tsx")) return "./bin/cli.js";
+        return bin;
+    }
     if (bin && "object" == typeof bin) {
         const transformed = {};
-        for (const [command, path] of Object.entries(bin))if (void 0 !== path) transformed[command] = transformExportPath(path, processTSExports);
+        for (const [command, path] of Object.entries(bin))if (void 0 !== path) if (path.endsWith(".ts") || path.endsWith(".tsx")) transformed[command] = `./bin/${command}.js`;
+        else transformed[command] = path;
         return transformed;
     }
     return bin;
@@ -1514,4 +1721,4 @@ const PackageJsonTransformPlugin = (options = {})=>{
         });
     }
 }
-export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, NodeLibraryBuilder, PackageJsonTransformPlugin, PackageJsonTransformer, PnpmCatalog, collectDtsFiles, ensureTempDeclarationDir, findTsConfig, generateTsgoArgs, getTsgoBinPath, getUnscopedPackageName, 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.2",
+	"version": "0.2.1",
 	"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",
@@ -24,16 +24,14 @@
 			"types": "./index.d.ts",
 			"import": "./index.js"
 		},
-		"./tsconfig/root.json": "./public/tsconfig/root.json",
-		"./tsconfig/node/ecma/lib.json": "./public/tsconfig/node/ecma/lib.json",
-		"./tsconfig/node/ecma/lib-compat.json": "./public/tsconfig/node/ecma/lib-compat.json",
-		"./tsconfig/node/ecma/bundle.json": "./public/tsconfig/node/ecma/bundle.json",
-		"./tsconfig/node/ecma/bundleless.json": "./public/tsconfig/node/ecma/bundleless.json"
+		"./tsconfig/root.json": "./tsconfig/root.json",
+		"./tsconfig/ecma/lib.json": "./tsconfig/ecma/lib.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",
 		"picocolors": "^1.1.1",
 		"sort-package-json": "^3.6.0",
 		"tmp": "^0.2.5",
@@ -57,20 +55,6 @@
 			"optional": false
 		}
 	},
-	"devEngines": {
-		"packageManager": {
-			"name": "pnpm",
-			"version": "10.28.0",
-			"onFail": "ignore"
-		},
-		"runtime": [
-			{
-				"name": "node",
-				"version": "24.11.0",
-				"onFail": "ignore"
-			}
-		]
-	},
 	"files": [
 		"!rslib-builder.api.json",
 		"LICENSE",
@@ -79,7 +63,8 @@
 		"index.js",
 		"package.json",
 		"rslib-runtime.js",
-		"tsconfig/node/ecma/lib.json",
-		"tsconfig/root.json"
+		"tsconfig/ecma/lib.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"
+    }
+  ]
+}