@savvy-web/rslib-builder 0.2.2 → 0.3.0

package/index.d.ts

@@ -84,10 +84,12 @@ export declare interface ApiModelOptions {
      *
      * @example
      * ```typescript
-     * apiModel: {
+     * import type { ApiModelOptions } from '@savvy-web/rslib-builder';
+     *
+     * const apiModel: ApiModelOptions = {
      *   enabled: true,
-     *   localPaths: ["../docs-site/lib/packages/my-package"],
-     * }
+     *   localPaths: ['../docs-site/lib/packages/my-package'],
+     * };
      * ```
      */
     localPaths?: string[];
@@ -102,12 +104,14 @@ export declare interface ApiModelOptions {
      *
      * @example
      * ```typescript
-     * apiModel: {
+     * import type { ApiModelOptions } from '@savvy-web/rslib-builder';
+     *
+     * const apiModel: ApiModelOptions = {
      *   enabled: true,
      *   tsdoc: {
-     *     tagDefinitions: [{ tagName: "@error", syntaxKind: "inline" }]
-     *   }
-     * }
+     *     tagDefinitions: [{ tagName: '@error', syntaxKind: 'inline' }],
+     *   },
+     * };
      * ```
      */
     tsdoc?: TsDocOptions;
@@ -119,30 +123,109 @@ export declare interface ApiModelOptions {
 }
 
 /**
- * Plugin to read package.json and configure entry points based on exports.
+ * Plugin to automatically detect and configure entry points from package.json exports.
+ *
+ * @remarks
+ * This plugin reads your package.json exports field and automatically configures
+ * RSlib entry points, eliminating the need to manually specify entries in your config.
+ *
+ * ## Features
+ *
+ * - Automatically extracts entry points from package.json `exports` field
+ * - Supports both string and object export values
+ * - Handles bin field entries for CLI tools
+ * - Exposes entrypoints map for other plugins to consume
+ *
+ * ## How It Works
+ *
+ * 1. Reads package.json from the project root
+ * 2. Extracts entry points from the `exports` field
+ * 3. Configures RSlib with the discovered entries
+ * 4. Exposes the entrypoints map via `api.useExposed("entrypoints")`
+ *
+ * @param options - Plugin configuration options
+ *
+ * @example
+ * Basic usage (entries detected from package.json):
+ * ```typescript
+ * import { AutoEntryPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default {
+ *   plugins: [AutoEntryPlugin()],
+ * };
+ * ```
+ *
+ * @example
+ * With nested directory output:
+ * ```typescript
+ * import { AutoEntryPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default {
+ *   plugins: [
+ *     AutoEntryPlugin({ exportsAsIndexes: true }),
+ *   ],
+ * };
+ * ```
  *
- * @param options - Plugin configuration options with properties:
- *   - `exportsAsIndexes`: When true, export paths create index files in nested directories
  * @public
  */
-export declare const AutoEntryPlugin: (options?: {
-    exportsAsIndexes?: boolean | undefined;
-} | undefined) => RsbuildPlugin;
+export declare const AutoEntryPlugin: (options?: AutoEntryPluginOptions | undefined) => RsbuildPlugin;
 
 /**
+ * Options for the AutoEntryPlugin.
  * @public
  */
-export declare type BuildTarget = "dev" | "npm";
+export declare interface AutoEntryPluginOptions {
+    /**
+     * When enabled, export paths create `index.js` files in nested directories
+     * instead of using the export name as the filename.
+     *
+     * @remarks
+     * This is useful when you want cleaner import paths that don't require
+     * specifying a filename, relying on Node's directory index resolution.
+     *
+     * @example
+     * With `exportsAsIndexes: true` and this package.json:
+     * ```json
+     * {
+     *   "exports": {
+     *     ".": "./src/index.ts",
+     *     "./utils": "./src/utils/index.ts"
+     *   }
+     * }
+     * ```
+     *
+     * Output structure:
+     * ```
+     * dist/
+     *   index.js
+     *   utils/
+     *     index.js
+     * ```
+     *
+     * @defaultValue false
+     */
+    exportsAsIndexes?: boolean;
+}
 
 /**
- * Recursively collects all .d.ts and .d.ts.map files from a directory.
+ * Build target environment for library output.
+ *
+ * @remarks
+ * Each target produces different output optimizations:
+ * - `"dev"`: Development build with source maps for debugging
+ * - `"npm"`: Production build optimized for npm publishing
+ *
+ * @example
+ * Specifying targets via CLI:
+ * ```bash
+ * rslib build --env-mode dev
+ * rslib build --env-mode npm
+ * ```
  *
  * @public
  */
-export declare function collectDtsFiles(dir: string, baseDir?: string): Promise<Array<{
-    path: string;
-    relativePath: string;
-}>>;
+export declare type BuildTarget = "dev" | "npm";
 
 /**
  * Plugin to generate TypeScript declaration files using tsgo and emit them through Rslib's asset pipeline.
@@ -180,7 +263,7 @@ export declare function collectDtsFiles(dir: string, baseDir?: string): Promise<
  *
  * @example
  * ```typescript
- * import { DtsPlugin } from "@savvy-web/shared/rslib";
+ * import { DtsPlugin } from "@savvy-web/rslib-builder";
  *
  * export default {
  *   plugins: [
@@ -261,196 +344,173 @@ export declare interface DtsPluginOptions {
 }
 
 /**
- * Ensures a temp directory exists for declaration file generation.
- * @internal
- */
-export declare function ensureTempDeclarationDir(cwd: string, name: string): Promise<string>;
-
-/**
- * Extracts TypeScript entry points from package.json for build configuration.
+ * Plugin to manage the `files` array in package.json for npm publishing.
  *
  * @remarks
- * This class analyzes package.json export and bin configurations to identify
- * TypeScript source files that need to be built. It handles various export
- * formats and automatically maps JavaScript output paths back to their
- * TypeScript source files.
- *
- * **Export Path Mapping:**
- * - 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
- *
- * **Source Path Resolution:**
- * - Prioritizes TypeScript files (.ts/.tsx) over JavaScript files
- * - Maps /dist/ JavaScript paths back to /src/ TypeScript sources
- * - Supports conditional exports (import, default, types fields)
+ * This plugin automatically populates the `files` field in the output package.json
+ * with all compiled assets and essential files. Other plugins can add files via
+ * the shared `files-array` exposed through the Rsbuild API.
+ *
+ * ## Files Included
+ *
+ * - Essential files: package.json, README.md, LICENSE
+ * - All compiled JavaScript files
+ * - All declaration files (.d.ts)
+ * - Files added by other plugins via `api.useExposed("files-array")`
+ *
+ * ## Files Excluded
+ *
+ * - Source map files (.map)
+ * - Files prefixed with `!` in the files array (negated patterns)
+ *
+ * ## Plugin Interoperability
+ *
+ * Other plugins can add files to the array:
+ * ```typescript
+ * const filesArray = api.useExposed("files-array") as Set<string>;
+ * filesArray.add("my-custom-file.json");
+ * ```
+ *
+ * @param options - Plugin configuration options
  *
  * @example
+ * Basic usage:
  * ```typescript
- * const extractor = new EntryExtractor();
+ * import { FilesArrayPlugin } from '@savvy-web/rslib-builder';
  *
- * const packageJson = {
- *   exports: {
- *     ".": "./src/index.ts",
- *     "./utils": "./src/utils.ts",
- *   },
- *   bin: {
- *     "my-cli": "./src/bin/cli.ts"
- *   }
+ * export default {
+ *   plugins: [
+ *     FilesArrayPlugin({ target: 'npm' }),
+ *   ],
  * };
+ * ```
  *
- * const result = extractor.extract(packageJson);
- * console.log(result.entries);
- * // {
- * //   "index": "./src/index.ts",
- * //   "utils": "./src/utils.ts",
- * //   "bin/my-cli": "./src/bin/cli.ts"
- * // }
+ * @example
+ * With custom file transformation:
+ * ```typescript
+ * import { FilesArrayPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default {
+ *   plugins: [
+ *     FilesArrayPlugin({
+ *       target: 'npm',
+ *       transformFiles({ filesArray }) {
+ *         filesArray.add('CHANGELOG.md');
+ *       },
+ *     }),
+ *   ],
+ * };
  * ```
  *
  * @public
  */
-export declare class EntryExtractor {
-    private readonly options;
-    constructor(options?: EntryExtractorOptions);
-    /**
-     * Extracts entry points from package.json exports and bin fields.
-     *
-     * @param packageJson - The package.json to extract entries from
-     * @returns Object containing the extracted entries
-     */
-    extract(packageJson: PackageJson): ExtractedEntries;
-    /**
-     * Extracts entries from the exports field.
-     */
-    private extractFromExports;
-    /**
-     * Extracts entries from the bin field.
-     */
-    private extractFromBin;
-    /**
-     * Resolves a source path from various export value formats.
-     */
-    private resolveSourcePath;
-    /**
-     * Resolves a path to its TypeScript source equivalent.
-     * Maps /dist/ JavaScript paths back to /src/ TypeScript sources.
-     */
-    private resolveToTypeScript;
-    /**
-     * Checks if a path points to a TypeScript file.
-     */
-    private isTypeScriptFile;
-    /**
-     * Creates an entry name from an export key.
-     */
-    private createEntryName;
-}
-
-/**
- * Options for entry extraction.
- * @public
- */
-export declare interface EntryExtractorOptions {
-    /**
-     * When true, export paths create index files in nested directories.
-     * "./foo/bar" becomes "foo/bar/index" instead of "foo-bar".
-     */
-    exportsAsIndexes?: boolean;
-}
-
-/**
- * Result of entry extraction.
- * @public
- */
-export declare interface ExtractedEntries {
-    /**
-     * Entry name to TypeScript source path mapping.
-     */
-    entries: Record<string, string>;
-}
-
-/**
- * Plugin to manage the files array in package.json
- * Adds essential files like package.json, README.md, LICENSE and compiled outputs
- * Other plugins can use api.useExposed("files-array") to add additional files
- * @public
- */
 export declare const FilesArrayPlugin: <TTarget extends string = string>(options?: FilesArrayPluginOptions<TTarget> | undefined) => RsbuildPlugin;
 
 /**
+ * Options for the FilesArrayPlugin.
+ *
+ * @typeParam TTarget - The build target type, defaults to string
+ *
  * @public
  */
 export declare interface FilesArrayPluginOptions<TTarget extends string = string> {
     /**
      * Optional callback to transform files after they're built but before the files array is finalized.
-     * Called in the additional stage, after all assets are created.
+     *
+     * @remarks
+     * Called during the "additional" stage of asset processing, after all other assets are created.
+     * Use this to copy/rename files or add additional files to the build output.
+     *
+     * @param context - Transform context containing:
+     *   - `compilation`: Rspack compilation object with assets
+     *   - `filesArray`: Set of files to be included in package.json `files` field
+     *   - `target`: Current build target
+     *
+     * @example
+     * ```typescript
+     * import type { FilesArrayPluginOptions } from '@savvy-web/rslib-builder';
+     *
+     * const options: FilesArrayPluginOptions = {
+     *   target: 'npm',
+     *   transformFiles({ compilation, filesArray }) {
+     *     // Add a custom file to the output
+     *     filesArray.add('custom-file.txt');
+     *   },
+     * };
+     * ```
      */
     transformFiles?: (context: {
         /** Rspack compilation object with assets */
         compilation: {
             assets: Record<string, unknown>;
         };
+        /** Set of files to include in package.json files array */
         filesArray: Set<string>;
+        /** Current build target */
         target: TTarget;
     }) => void | Promise<void>;
-    /** Build target (dev/npm/jsr) */
+    /**
+     * Build target identifier (e.g., "dev", "npm").
+     *
+     * @remarks
+     * Passed to the `transformFiles` callback to allow target-specific transformations.
+     */
     target: TTarget;
 }
 
 /**
- * Finds the TypeScript config file.
- * @internal
- */
-export declare function findTsConfig(cwd: string, tsconfigPath?: string): string | null;
-
-/**
- * Flexible type definition for package.json exports field that accommodates various export formats.
+ * Builder for Node.js ESM libraries using RSlib.
  *
  * @remarks
- * This type extends the standard PackageJson.Exports to allow for custom fields and nested
- * structures commonly found in complex package configurations. It supports:
- * - Standard exports objects with conditions
- * - Custom field exports
- * - Array-based exports (for fallbacks)
- * - Null/undefined values for conditional exports
- */
-declare type FlexibleExports = PackageJson.Exports | Record<string, unknown> | FlexibleExports[] | undefined | null;
-
-/**
- * Generates command-line arguments for tsgo.
+ * NodeLibraryBuilder provides a high-level API for building modern ESM Node.js libraries.
+ * It handles TypeScript compilation, declaration bundling, package.json transformation,
+ * and multi-target builds (dev and npm).
+ *
+ * Features:
+ * - Automatic entry point detection from package.json exports
+ * - TypeScript declarations via tsgo + API Extractor
+ * - pnpm catalog and workspace protocol resolution
+ * - Source maps for development builds
+ * - Configurable external dependencies and type bundling
+ *
+ * @example
+ * Basic usage in `rslib.config.ts`:
+ * ```typescript
+ * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+ *
+ * export default NodeLibraryBuilder.create();
+ * ```
+ *
+ * @example
+ * With custom options:
+ * ```typescript
+ * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+ *
+ * export default NodeLibraryBuilder.create({
+ *   externals: ['@rslib/core', '@rsbuild/core'],
+ *   dtsBundledPackages: ['picocolors'],
+ *   apiModel: true,
+ *   transform({ target, pkg }) {
+ *     if (target === 'npm') {
+ *       delete pkg.devDependencies;
+ *     }
+ *     return pkg;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * Build commands:
+ * ```bash
+ * # Development build (with source maps)
+ * rslib build --env-mode dev
+ *
+ * # Production build (for npm publishing)
+ * rslib build --env-mode npm
+ * ```
  *
  * @public
  */
-export declare function generateTsgoArgs(options: {
-    configPath: string;
-    declarationDir: string;
-    rootDir?: string;
-    tsBuildInfoFile?: string;
-}): string[];
-
-/**
- * Gets the path to the tsgo (TypeScript native compiler) executable.
- * Uses workspace-tools to find the workspace root and searches for tsgo binary.
- * Supports npm, pnpm, yarn, rush, and lerna workspaces.
- * @returns The absolute path to the tsgo binary
- * @internal
- */
-export declare function getTsgoBinPath(): string;
-
-/**
- * Extracts the unscoped package name from a potentially scoped package name.
- * @param name - The package name (e.g., `@scope/package` or `package`)
- * @returns The unscoped name (e.g., `package`)
- * @internal
- */
-export declare function getUnscopedPackageName(name: string): string;
-
-/**
- * @public
- * Node library builder class
- */
 export declare class NodeLibraryBuilder {
     static DEFAULT_OPTIONS: NodeLibraryBuilderOptions;
     static mergeOptions(options?: Partial<NodeLibraryBuilderOptions>): NodeLibraryBuilderOptions;
@@ -518,9 +578,11 @@ export declare interface NodeLibraryBuilderOptions {
      *
      * @example
      * ```typescript
-     * NodeLibraryBuilder.create({
-     *   externals: ['@rslib/core', '@rsbuild/core']
-     * })
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   externals: ['@rslib/core', '@rsbuild/core'],
+     * });
      * ```
      */
     externals?: (string | RegExp)[];
@@ -536,9 +598,11 @@ export declare interface NodeLibraryBuilderOptions {
      *
      * @example
      * ```typescript
-     * NodeLibraryBuilder.create({
-     *   dtsBundledPackages: ['@pnpm/lockfile.types', '@pnpm/types', 'picocolors']
-     * })
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   dtsBundledPackages: ['@pnpm/lockfile.types', '@pnpm/types', 'picocolors'],
+     * });
      * ```
      */
     dtsBundledPackages?: string[];
@@ -553,16 +617,18 @@ export declare interface NodeLibraryBuilderOptions {
      *
      * @example
      * ```typescript
-     * NodeLibraryBuilder.create({
-     *   transformFiles({ compilation, filesArray, target }) {
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   transformFiles({ compilation, filesArray }) {
      *     // Copy index.cjs to .pnpmfile.cjs
      *     const indexAsset = compilation.assets['index.cjs'];
      *     if (indexAsset) {
      *       compilation.assets['.pnpmfile.cjs'] = indexAsset;
      *       filesArray.add('.pnpmfile.cjs');
      *     }
-     *   }
-     * })
+     *   },
+     * });
      * ```
      */
     transformFiles?: (context: {
@@ -582,16 +648,17 @@ export declare interface NodeLibraryBuilderOptions {
      *
      * @example
      * ```typescript
-     * NodeLibraryBuilder.create({
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
      *   transform({ target, pkg }) {
      *     if (target === 'npm') {
-     *       // Mutation approach
      *       delete pkg.devDependencies;
      *       delete pkg.scripts;
      *     }
      *     return pkg;
-     *   }
-     * })
+     *   },
+     * });
      * ```
      */
     transform?: TransformPackageJsonFn;
@@ -606,282 +673,213 @@ export declare interface NodeLibraryBuilderOptions {
      * The file is emitted to dist but excluded from npm publish (added as negated pattern in `files` array).
      *
      * @example
+     * Enable API model generation with defaults:
      * ```typescript
-     * // Enable API model generation with defaults
-     * NodeLibraryBuilder.create({
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
      *   apiModel: true,
-     * })
+     * });
+     * ```
+     *
+     * @example
+     * Enable with custom filename:
+     * ```typescript
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
      *
-     * // Enable with custom filename
-     * NodeLibraryBuilder.create({
+     * export default NodeLibraryBuilder.create({
      *   apiModel: {
      *     enabled: true,
-     *     filename: "my-package.api.json",
+     *     filename: 'my-package.api.json',
      *   },
-     * })
+     * });
      * ```
      */
     apiModel?: ApiModelOptions | boolean;
 }
 
 /**
- * Transforms package.json for build output and publishing.
+ * Plugin to transform package.json for distribution.
  *
  * @remarks
- * This class consolidates all package.json transformation logic including:
- * - Path transformations (src/ to dist/, .ts to .js)
- * - Export conditions generation (types, import, require)
- * - Bin field transformations
- * - PNPM catalog and workspace resolution
- * - Field cleanup for publishing
+ * This plugin processes the source package.json and transforms it for the build output.
+ * It handles path transformations, pnpm catalog/workspace resolution, and field cleanup.
+ *
+ * ## Transformations Applied
+ *
+ * - **Path Updates**: Converts source paths to output paths (e.g., `./src/index.ts` → `./index.js`)
+ * - **Type Conditions**: Adds `types` fields to exports pointing to `.d.ts` files
+ * - **pnpm Resolution**: Resolves `catalog:` and `workspace:*` dependency versions
+ * - **Field Cleanup**: Removes `scripts`, `publishConfig`, and other dev-only fields
+ * - **Private Flag**: Sets based on `publishConfig.access` or `forcePrivate` option
+ *
+ * ## Plugin Interoperability
+ *
+ * - Consumes `entrypoints` map from AutoEntryPlugin
+ * - Consumes `exportToOutputMap` for exportsAsIndexes mode
+ * - Exposes `files-cache` for asset caching
+ * - Consumes `use-rollup-types` flag from DtsPlugin
+ *
+ * @param options - Plugin configuration options
  *
  * @example
+ * Basic usage:
  * ```typescript
- * const transformer = new PackageJsonTransformer({
- *   processTSExports: true,
- *   collapseIndex: true,
- * });
+ * import { PackageJsonTransformPlugin } from '@savvy-web/rslib-builder';
  *
- * // For production builds (resolves catalog: and workspace: references)
- * const prodPkg = await transformer.transform(packageJson, { isProduction: true });
+ * export default {
+ *   plugins: [
+ *     PackageJsonTransformPlugin({
+ *       bundle: true,
+ *       processTSExports: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * @example
+ * With custom transform:
+ * ```typescript
+ * import { PackageJsonTransformPlugin } from '@savvy-web/rslib-builder';
  *
- * // For development builds (preserves workspace links)
- * const devPkg = await transformer.transform(packageJson, { isProduction: false });
+ * export default {
+ *   plugins: [
+ *     PackageJsonTransformPlugin({
+ *       target: 'npm',
+ *       transform(pkg) {
+ *         delete pkg.devDependencies;
+ *         return pkg;
+ *       },
+ *     }),
+ *   ],
+ * };
  * ```
  *
  * @public
  */
-export declare class PackageJsonTransformer {
-    private readonly options;
-    private readonly pnpmCatalog;
-    constructor(options?: PackageJsonTransformOptions);
+export declare const PackageJsonTransformPlugin: (options?: PackageJsonTransformPluginOptions) => RsbuildPlugin;
+
+/**
+ * Options for the PackageJsonTransformPlugin.
+ *
+ * @public
+ */
+export declare interface PackageJsonTransformPluginOptions {
     /**
-     * Transforms a single export path for RSLib compatibility.
+     * Override the package name in the output package.json.
      *
      * @remarks
-     * Performs several transformations:
-     * 1. Strips source directory prefixes (exports/, public/, src/)
-     * 2. Converts TypeScript extensions to JavaScript
-     * 3. Preserves bin/ prefix for executables
-     *
-     * @param path - The file path to transform
-     * @returns The transformed path
+     * - When a string is provided, the package name is replaced with that value
+     * - When `true`, the original name is preserved (no override)
+     * - When undefined, the original name is preserved
      *
      * @example
      * ```typescript
-     * transformer.transformExportPath("./src/index.ts"); // "./index.js"
-     * transformer.transformExportPath("./bin/cli.ts");   // "./bin/cli.js"
-     * ```
-     */
-    transformExportPath(path: string): string;
-    /**
-     * Creates a TypeScript declaration file path from a JavaScript file path.
-     *
-     * @param jsPath - The JavaScript file path
-     * @returns The corresponding .d.ts file path
+     * import type { PackageJsonTransformPluginOptions } from '@savvy-web/rslib-builder';
      *
-     * @example
-     * ```typescript
-     * transformer.createTypePath("./index.js");      // "./index.d.ts"
-     * transformer.createTypePath("./rslib/index.js"); // "./rslib.d.ts" (bundled)
+     * const options: PackageJsonTransformPluginOptions = {
+     *   name: '@scope/my-package-dist',
+     * };
      * ```
      */
-    createTypePath(jsPath: string): string;
-    /**
-     * Transforms package.json exports field recursively.
-     *
-     * @param exports - The exports value to transform
-     * @param exportKey - The current export key for context
-     * @returns The transformed exports value
-     */
-    transformExports(exports: FlexibleExports, exportKey?: string): FlexibleExports;
+    name?: string | true;
     /**
-     * Transforms the bin field for build output.
+     * Force the output package.json to have `"private": true`.
      *
      * @remarks
-     * TypeScript bin entries are compiled to `./bin/{command-name}.js` by RSlib.
-     * Non-TypeScript entries (shell scripts, compiled JS) are preserved as-is.
+     * Useful for development builds that should never be published.
+     * When true, overrides the `publishConfig.access` setting.
      *
-     * @param bin - The bin field from package.json
-     * @returns The transformed bin field
+     * @defaultValue false
      */
-    transformBin(bin: PackageJson["bin"]): PackageJson["bin"];
+    forcePrivate?: boolean;
     /**
-     * Performs the complete package.json transformation.
+     * Whether to process TypeScript exports and generate type conditions.
      *
-     * @param packageJson - The source package.json
-     * @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?: {
-        isProduction?: boolean;
-        customTransform?: (pkg: PackageJson) => PackageJson;
-    }): Promise<PackageJson>;
-    private applyPnpmTransformations;
-    /**
-     * Applies RSLib-specific transformations.
-     */
-    private applyRslibTransformations;
-    /**
-     * Transforms a string export value.
-     */
-    private transformStringExport;
-    /**
-     * Transforms an object export value.
-     */
-    private transformObjectExports;
-    /**
-     * Determines if an export object represents export conditions.
-     */
-    private isConditionsObject;
-    /**
-     * Transforms a single export entry.
-     */
-    private transformExportEntry;
-}
-
-/**
- * Options for transforming package.json.
- * @public
- */
-export declare interface PackageJsonTransformOptions {
-    /**
-     * Whether to process TypeScript exports (convert .ts to .js and add types field).
-     * @defaultValue true
+     * @remarks
+     * When enabled, transforms export paths from `.ts` to `.js` and adds
+     * `types` conditions pointing to the corresponding `.d.ts` files.
+     *
+     * @example
+     * Input: `"./src/index.ts"`
+     * Output: `{ "types": "./index.d.ts", "import": "./index.js" }`
      */
     processTSExports?: boolean;
     /**
-     * Whether to collapse index files (./foo/index.ts becomes ./foo.js).
-     * This is typically true for bundled builds.
+     * Whether the build is in bundle mode.
+     *
+     * @remarks
+     * Affects export path transformations - in bundle mode, nested index files
+     * are collapsed (e.g., `./utils/index.ts` becomes `./utils.js`).
+     *
      * @defaultValue false
      */
-    collapseIndex?: boolean;
-    /**
-     * Map of export paths to entry files (from AutoEntryPlugin).
-     */
-    entrypoints?: Map<string, string>;
-    /**
-     * Map of export paths to output files (for exportsAsIndexes mode).
-     */
-    exportToOutputMap?: Map<string, string>;
-}
-
-/**
- * Plugin to process package.json for distribution
- * @public
- */
-export declare const PackageJsonTransformPlugin: (options?: PackageJsonTransformPluginOptions) => RsbuildPlugin;
-
-/**
- * @public
- */
-export declare interface PackageJsonTransformPluginOptions {
-    /** Override the name property of the source package.json when building to a target */
-    name?: string | true;
-    /** Whether to force include private packages (with "private": true) in the output */
-    forcePrivate?: boolean;
-    /** Whether to process package.json exports of into  */
-    processTSExports?: boolean;
-    /** Whether the build is in bundle mode (affects export path transformation) */
     bundle?: boolean;
-    /** Build target (dev, npm) - used for custom transformations */
-    target?: string;
-    /** Optional transform function to modify package.json after standard transformations */
-    transform?: (pkg: PackageJson) => PackageJson;
-}
-
-/**
- * Manages PNPM catalog resolution with caching.
- *
- * @remarks
- * This class handles the resolution of PNPM-specific dependency references:
- * - `catalog:` references to centralized version definitions
- * - `workspace:` references to local workspace packages
- *
- * The class caches the catalog data based on file modification time to avoid
- * repeated filesystem operations during builds.
- *
- * @example
- * ```typescript
- * const catalog = new PnpmCatalog();
- *
- * // Get the catalog data
- * const versions = await catalog.getCatalog();
- * console.log(versions);
- * // { "react": "^18.2.0", "typescript": "^5.0.0" }
- *
- * // Resolve package.json dependencies
- * const resolved = await catalog.resolvePackageJson(packageJson);
- * ```
- *
- * @public
- */
-export declare class PnpmCatalog {
-    private catalogCache;
-    private catalogCacheMtime;
-    private cachedWorkspaceRoot;
     /**
-     * Clears the cached catalog data.
+     * Build target identifier for custom transformations.
      *
      * @remarks
-     * Useful in testing scenarios to ensure clean state between tests.
+     * Passed to the transform function to allow target-specific modifications.
+     * Common values: "dev", "npm"
      */
-    clearCache(): void;
+    target?: string;
     /**
-     * Gets the PNPM catalog from pnpm-workspace.yaml.
+     * Custom transform function to modify package.json after standard transformations.
      *
      * @remarks
-     * The catalog is cached based on file modification time. If the file hasn't
-     * changed since the last read, the cached version is returned.
+     * Called after all built-in transformations (path updates, pnpm resolution, etc.)
+     * are applied. Mutations to the object are also supported.
      *
-     * @returns The catalog mapping dependency names to versions
-     */
-    getCatalog(): Promise<Record<string, string>>;
-    /**
-     * Resolves catalog: and workspace: references in a package.json.
+     * @param pkg - The package.json object after standard transformations
+     * @returns The modified package.json object
      *
-     * @param packageJson - The package.json to resolve
-     * @param dir - The directory containing the package (defaults to cwd)
-     * @returns The resolved package.json
+     * @example
+     * ```typescript
+     * import type { PackageJsonTransformPluginOptions } from '@savvy-web/rslib-builder';
      *
-     * @throws When resolution fails for critical dependencies
-     */
-    resolvePackageJson(packageJson: PackageJson, dir?: string): Promise<PackageJson>;
-    /**
-     * Collects dependencies with a specific prefix (catalog: or workspace:).
-     */
-    private collectDependencies;
-    /**
-     * Logs resolved dependencies in a formatted way.
-     */
-    private logResolvedDependencies;
-    /**
-     * Validates that no unresolved catalog: or workspace: references remain.
+     * const options: PackageJsonTransformPluginOptions = {
+     *   transform(pkg) {
+     *     delete pkg.devDependencies;
+     *     pkg.publishConfig = { access: 'public' };
+     *     return pkg;
+     *   },
+     * };
+     * ```
      */
-    private validateNoUnresolvedReferences;
+    transform?: (pkg: PackageJson) => PackageJson;
 }
 
 /**
  * Async RSLib configuration function type.
  * @public
  */
-export declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
+declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
 
 /**
- * Strips sourceMappingURL comment from declaration file content.
- * This removes comments like: `//# source` + `MappingURL=index.d.ts.map`
+ * Function to transform package.json during the build process.
  *
  * @remarks
- * Source maps are preserved in the temp directory for API Extractor documentation
- * but are excluded from the final dist output to reduce package size.
+ * This function is called after all standard transformations are applied,
+ * allowing you to modify the package.json before it's written to the output directory.
+ * Mutations to the `pkg` object are also supported.
  *
- * @public
- */
-export declare function stripSourceMapComment(content: string): string;
-
-/**
+ * @param context - Transform context containing:
+ *   - `target`: The current build target ("dev" or "npm")
+ *   - `pkg`: The package.json object to transform
+ * @returns The modified package.json object
+ *
+ * @example
+ * ```typescript
+ * import type { TransformPackageJsonFn } from '@savvy-web/rslib-builder';
+ *
+ * const transform: TransformPackageJsonFn = ({ target, pkg }) => {
+ *   if (target === 'npm') {
+ *     delete pkg.devDependencies;
+ *     delete pkg.scripts;
+ *   }
+ *   return pkg;
+ * };
+ * ```
  * @public
  */
 export declare type TransformPackageJsonFn = (context: {
@@ -890,8 +888,50 @@ export declare type TransformPackageJsonFn = (context: {
 }) => PackageJson;
 
 /**
- * Builder for TSDoc configuration files.
- * Handles tag group expansion, config generation, and file persistence.
+ * Builder for TSDoc configuration files used by API Extractor.
+ *
+ * @remarks
+ * This class provides utilities for generating `tsdoc.json` configuration files
+ * that control TSDoc tag support during API documentation generation.
+ *
+ * ## Features
+ *
+ * - Expands tag groups into individual tag definitions
+ * - Generates properly formatted tsdoc.json files
+ * - Handles config persistence based on environment (CI vs local)
+ * - Supports custom tag definitions
+ *
+ * ## Tag Groups
+ *
+ * The builder supports three standardization groups from `\@microsoft/tsdoc`:
+ * - `core`: Essential tags (`\@param`, `\@returns`, `\@remarks`, etc.)
+ * - `extended`: Additional tags (`\@example`, `\@defaultValue`, `\@see`, etc.)
+ * - `discretionary`: Release tags (`\@alpha`, `\@beta`, `\@public`, `\@internal`)
+ *
+ * @example
+ * Build tag configuration from options:
+ * ```typescript
+ * import { TsDocConfigBuilder } from '@savvy-web/rslib-builder';
+ *
+ * const config = TsDocConfigBuilder.build({
+ *   groups: ['core', 'extended'],
+ *   tagDefinitions: [
+ *     { tagName: '@error', syntaxKind: 'inline' },
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * Write a tsdoc.json file:
+ * ```typescript
+ * import { TsDocConfigBuilder } from '@savvy-web/rslib-builder';
+ *
+ * const configPath = await TsDocConfigBuilder.writeConfigFile(
+ *   { groups: ['core', 'extended', 'discretionary'] },
+ *   process.cwd(),
+ * );
+ * ```
+ *
  * @public
  */
 export declare class TsDocConfigBuilder {
@@ -1016,10 +1056,12 @@ export declare interface TsDocOptions {
      *
      * @example
      * ```typescript
-     * tagDefinitions: [
-     *   { tagName: "@error", syntaxKind: "inline" },
-     *   { tagName: "@category", syntaxKind: "block", allowMultiple: false }
-     * ]
+     * import type { TsDocTagDefinition } from '@savvy-web/rslib-builder';
+     *
+     * const tagDefinitions: TsDocTagDefinition[] = [
+     *   { tagName: '@error', syntaxKind: 'inline' },
+     *   { tagName: '@category', syntaxKind: 'block', allowMultiple: false },
+     * ];
      * ```
      */
     tagDefinitions?: TsDocTagDefinition[];
@@ -1028,9 +1070,9 @@ export declare interface TsDocOptions {
      * Tags from enabled groups and custom tagDefinitions are auto-supported.
      *
      * @example
+     * Disable \@beta even though "extended" group is enabled:
      * ```typescript
-     * // Disable @beta even though "extended" group is enabled
-     * supportForTags: { "@beta": false }
+     * const supportForTags: Record<string, boolean> = { '@beta': false };
      * ```
      */
     supportForTags?: Record<string, boolean>;
@@ -1054,15 +1096,6 @@ export declare interface TsDocOptions {
      * 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
      */
@@ -1084,6 +1117,27 @@ export declare interface TsDocTagDefinition {
 
 /**
  * TSDoc standardization groups for predefined tag sets.
+ *
+ * @remarks
+ * These groups correspond to the TSDoc specification's standardization levels
+ * as defined in `\@microsoft/tsdoc`. Each group contains a set of related tags:
+ *
+ * - `"core"`: Essential tags for basic documentation
+ *   (`\@param`, `\@returns`, `\@remarks`, `\@deprecated`, `\@privateRemarks`, etc.)
+ *
+ * - `"extended"`: Additional tags for richer documentation
+ *   (`\@example`, `\@defaultValue`, `\@see`, `\@throws`, `\@typeParam`, etc.)
+ *
+ * - `"discretionary"`: Release stage and visibility modifiers
+ *   (`\@alpha`, `\@beta`, `\@public`, `\@internal`, `\@experimental`)
+ *
+ * @example
+ * ```typescript
+ * import type { TsDocTagGroup } from '@savvy-web/rslib-builder';
+ *
+ * const groups: TsDocTagGroup[] = ['core', 'extended'];
+ * ```
+ *
  * @public
  */
 export declare type TsDocTagGroup = "core" | "extended" | "discretionary";