@savvy-web/rslib-builder 0.2.2 → 0.4.0

package/index.d.ts

@@ -46,6 +46,7 @@ import type { RawCopyPattern } from '@rspack/binding';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RslibConfig } from '@rslib/core';
 import type { SourceConfig } from '@rsbuild/core';
+import ts from 'typescript';
 
 /**
  * Options for API model generation.
@@ -84,10 +85,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 +105,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 +124,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 +264,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,195 +345,540 @@ export declare interface DtsPluginOptions {
 }
 
 /**
- * Ensures a temp directory exists for declaration file generation.
- * @internal
+ * Plugin to manage the `files` array in package.json for npm publishing.
+ *
+ * @remarks
+ * 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
+ * import { FilesArrayPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default {
+ *   plugins: [
+ *     FilesArrayPlugin({ target: 'npm' }),
+ *   ],
+ * };
+ * ```
+ *
+ * @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 function ensureTempDeclarationDir(cwd: string, name: string): Promise<string>;
+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.
+     *
+     * @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 identifier (e.g., "dev", "npm").
+     *
+     * @remarks
+     * Passed to the `transformFiles` callback to allow target-specific transformations.
+     */
+    target: TTarget;
+}
 
 /**
- * Extracts TypeScript entry points from package.json for build configuration.
+ * Analyzes TypeScript import relationships to discover all files
+ * reachable from specified entry points.
  *
  * @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 class uses the TypeScript compiler API to trace import statements
+ * and discover all files that are part of the public API. It handles:
+ *
+ * - Static imports: `import { foo } from "./module"`
+ * - Dynamic imports: `import("./module")`
+ * - Re-exports: `export * from "./module"` and `export { foo } from "./module"`
+ * - Circular imports (via visited set tracking)
+ *
+ * The class automatically filters out:
+ * - Files in node_modules
+ * - Declaration files (.d.ts)
+ * - Test files (*.test.ts, *.spec.ts)
+ * - Files in __test__ directories
+ *
+ * ## Static Methods vs Instance Methods
+ *
+ * For simple one-off analysis, use the static convenience methods:
+ * - {@link ImportGraph.fromEntries} - Trace from explicit entry paths
+ * - {@link ImportGraph.fromPackageExports} - Trace from package.json exports
+ *
+ * For repeated analysis or custom configuration, create an instance
+ * and use the instance methods which reuse the TypeScript program.
  *
  * @example
+ * Using static methods (recommended for most cases):
  * ```typescript
- * const extractor = new EntryExtractor();
+ * import { ImportGraph } from '@savvy-web/rslib-builder';
  *
- * const packageJson = {
- *   exports: {
- *     ".": "./src/index.ts",
- *     "./utils": "./src/utils.ts",
- *   },
- *   bin: {
- *     "my-cli": "./src/bin/cli.ts"
- *   }
- * };
+ * // Trace from explicit entries
+ * const result = ImportGraph.fromEntries(
+ *   ['./src/index.ts', './src/cli.ts'],
+ *   { rootDir: process.cwd() }
+ * );
+ *
+ * // Trace from package.json exports
+ * const result = ImportGraph.fromPackageExports(
+ *   './package.json',
+ *   { rootDir: process.cwd() }
+ * );
+ * ```
  *
- * 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
+ * Using instance methods (for repeated analysis):
+ * ```typescript
+ * import { ImportGraph } from '@savvy-web/rslib-builder';
+ *
+ * const graph = new ImportGraph({ rootDir: '/path/to/project' });
+ *
+ * // Reuses the TypeScript program across multiple calls
+ * const libResult = graph.traceFromEntries(['./src/index.ts']);
+ * const cliResult = graph.traceFromEntries(['./src/cli.ts']);
  * ```
  *
  * @public
  */
-export declare class EntryExtractor {
+export declare class ImportGraph {
     private readonly options;
-    constructor(options?: EntryExtractorOptions);
+    private readonly sys;
+    private program;
+    private compilerOptions;
+    private moduleResolutionCache;
+    constructor(options: ImportGraphOptions);
     /**
-     * Extracts entry points from package.json exports and bin fields.
+     * Trace all imports from the given entry points.
      *
-     * @param packageJson - The package.json to extract entries from
-     * @returns Object containing the extracted entries
+     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
+     * @returns Deduplicated list of all reachable TypeScript files
      */
-    extract(packageJson: PackageJson): ExtractedEntries;
+    traceFromEntries(entryPaths: string[]): ImportGraphResult;
     /**
-     * Extracts entries from the exports field.
+     * Trace imports from package.json exports.
+     *
+     * @remarks
+     * Convenience method that extracts entry points from package.json
+     * using EntryExtractor, then traces all imports from those entries.
+     *
+     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
+     * @returns Deduplicated list of all reachable TypeScript files
      */
-    private extractFromExports;
+    traceFromPackageExports(packageJsonPath: string): ImportGraphResult;
     /**
-     * Extracts entries from the bin field.
+     * Initialize the TypeScript program for module resolution.
      */
-    private extractFromBin;
+    private initializeProgram;
     /**
-     * Resolves a source path from various export value formats.
+     * Find tsconfig.json path.
      */
-    private resolveSourcePath;
+    private findTsConfig;
     /**
-     * Resolves a path to its TypeScript source equivalent.
-     * Maps /dist/ JavaScript paths back to /src/ TypeScript sources.
+     * Resolve entry path to absolute path.
      */
-    private resolveToTypeScript;
+    private resolveEntryPath;
     /**
-     * Checks if a path points to a TypeScript file.
+     * Recursively trace imports from a source file.
      */
-    private isTypeScriptFile;
+    private traceImports;
     /**
-     * Creates an entry name from an export key.
+     * Extract all import/export module specifiers from a source file.
      */
-    private createEntryName;
-}
-
-/**
- * Options for entry extraction.
- * @public
- */
-export declare interface EntryExtractorOptions {
+    private extractImports;
     /**
-     * When true, export paths create index files in nested directories.
-     * "./foo/bar" becomes "foo/bar/index" instead of "foo-bar".
+     * Resolve a module specifier to an absolute file path.
      */
-    exportsAsIndexes?: boolean;
+    private resolveImport;
+    /**
+     * Check if a path is an external module (node_modules).
+     */
+    private isExternalModule;
+    /**
+     * Check if a file should be included in results.
+     * Filters out test files and non-TypeScript files.
+     */
+    private isSourceFile;
+    /**
+     * Traces TypeScript imports from entry points.
+     *
+     * @remarks
+     * Static convenience method that creates an ImportGraph instance
+     * and traces imports in one call. For repeated analysis where you want
+     * to reuse the TypeScript program, create an instance and use
+     * {@link ImportGraph.traceFromEntries} instead.
+     *
+     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
+     * @param options - Import graph configuration options
+     * @returns All TypeScript files reachable from the entries
+     *
+     * @example
+     * ```typescript
+     * import { ImportGraph } from '@savvy-web/rslib-builder';
+     *
+     * const result = ImportGraph.fromEntries(
+     *   ['./src/index.ts', './src/cli.ts'],
+     *   { rootDir: process.cwd() }
+     * );
+     * console.log('Found files:', result.files);
+     * ```
+     */
+    static fromEntries(entryPaths: string[], options: ImportGraphOptions): ImportGraphResult;
+    /**
+     * Traces TypeScript imports from package.json exports.
+     *
+     * @remarks
+     * Static convenience method that extracts entry points from package.json exports
+     * and traces all imports to find public API files. For repeated analysis,
+     * create an instance and use {@link ImportGraph.traceFromPackageExports} instead.
+     *
+     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
+     * @param options - Import graph configuration options
+     * @returns All TypeScript files reachable from the package exports
+     *
+     * @example
+     * ```typescript
+     * import { ImportGraph } from '@savvy-web/rslib-builder';
+     *
+     * const result = ImportGraph.fromPackageExports(
+     *   './package.json',
+     *   { rootDir: process.cwd() }
+     * );
+     * console.log('Public API files:', result.files);
+     * ```
+     */
+    static fromPackageExports(packageJsonPath: string, options: ImportGraphOptions): ImportGraphResult;
 }
 
 /**
- * Result of entry extraction.
+ * Structured error from import graph analysis.
+ *
+ * @remarks
+ * Provides detailed error information including the error type for
+ * programmatic handling, a human-readable message, and the relevant
+ * file path when applicable.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphError } from '@savvy-web/rslib-builder';
+ *
+ * function handleErrors(errors: ImportGraphError[]): void {
+ *   for (const error of errors) {
+ *     switch (error.type) {
+ *       case 'tsconfig_not_found':
+ *         console.warn('No tsconfig.json found, using defaults');
+ *         break;
+ *       case 'entry_not_found':
+ *         console.error(`Missing entry: ${error.path}`);
+ *         break;
+ *       default:
+ *         console.error(error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
-export declare interface ExtractedEntries {
+export declare interface ImportGraphError {
     /**
-     * Entry name to TypeScript source path mapping.
+     * The type of error that occurred.
+     *
+     * @remarks
+     * Use this field for programmatic error handling to distinguish
+     * between different failure modes.
      */
-    entries: Record<string, string>;
+    type: ImportGraphErrorType;
+    /**
+     * Human-readable error message.
+     *
+     * @remarks
+     * Suitable for logging or displaying to users.
+     */
+    message: string;
+    /**
+     * The file path related to the error, if applicable.
+     *
+     * @remarks
+     * Present for errors related to specific files like missing entries
+     * or file read failures.
+     */
+    path?: 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
+ * Types of errors that can occur during import graph analysis.
+ *
+ * @remarks
+ * These error types allow consumers to handle different failure modes
+ * appropriately. For example, a missing tsconfig might be handled differently
+ * than a missing entry file.
+ *
  * @public
  */
-export declare const FilesArrayPlugin: <TTarget extends string = string>(options?: FilesArrayPluginOptions<TTarget> | undefined) => RsbuildPlugin;
+export declare type ImportGraphErrorType = "tsconfig_not_found" | "tsconfig_read_error" | "tsconfig_parse_error" | "package_json_not_found" | "package_json_parse_error" | "entry_not_found" | "file_read_error";
 
 /**
+ * Options for configuring the ImportGraph analyzer.
+ *
+ * @remarks
+ * These options control how the ImportGraph traverses and resolves
+ * TypeScript module imports. The `rootDir` is required and serves as
+ * the base for resolving relative paths and finding the tsconfig.json.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphOptions } from '@savvy-web/rslib-builder';
+ *
+ * const options: ImportGraphOptions = {
+ *   rootDir: '/path/to/project',
+ *   tsconfigPath: './tsconfig.build.json',
+ * };
+ * ```
+ *
  * @public
  */
-export declare interface FilesArrayPluginOptions<TTarget extends string = string> {
+export declare interface ImportGraphOptions {
     /**
-     * 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.
+     * The project root directory.
+     *
+     * @remarks
+     * All relative paths (entry points, tsconfig path) are resolved from this directory.
+     * This should typically be the package root containing your `package.json`.
      */
-    transformFiles?: (context: {
-        /** Rspack compilation object with assets */
-        compilation: {
-            assets: Record<string, unknown>;
-        };
-        filesArray: Set<string>;
-        target: TTarget;
-    }) => void | Promise<void>;
-    /** Build target (dev/npm/jsr) */
-    target: TTarget;
+    rootDir: string;
+    /**
+     * Custom path to the TypeScript configuration file.
+     *
+     * @remarks
+     * If not provided, the analyzer searches for `tsconfig.json` starting from `rootDir`
+     * and walking up the directory tree. The tsconfig is used for module resolution
+     * settings including path aliases and module resolution strategy.
+     *
+     * @defaultValue Searches for tsconfig.json from rootDir
+     */
+    tsconfigPath?: string;
+    /**
+     * Custom TypeScript system for file operations.
+     *
+     * @remarks
+     * This is primarily used for testing to provide a mock filesystem.
+     * In production use, this defaults to `ts.sys` which uses the real filesystem.
+     *
+     * @defaultValue ts.sys
+     * @internal
+     */
+    sys?: ts.System;
+    /**
+     * Additional patterns to exclude from results.
+     *
+     * @remarks
+     * Patterns are matched against file paths using simple string inclusion.
+     * Use this to exclude files that don't match the default test file patterns.
+     *
+     * The default exclusions are always applied:
+     * - `.test.` and `.spec.` files
+     * - `__test__` and `__tests__` directories
+     * - `.d.ts` declaration files
+     *
+     * @example
+     * ```typescript
+     * const graph = new ImportGraph({
+     *   rootDir: process.cwd(),
+     *   excludePatterns: ['/fixtures/', '/mocks/', '.stories.'],
+     * });
+     * ```
+     *
+     * @defaultValue []
+     */
+    excludePatterns?: string[];
 }
 
 /**
- * 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.
+ * Result of import graph analysis.
  *
  * @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.
+ * Contains the complete set of TypeScript source files discovered by tracing
+ * imports from entry points. The analysis is non-fatal: errors are collected
+ * and tracing continues for other paths even when some imports fail to resolve.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphResult } from '@savvy-web/rslib-builder';
+ *
+ * function processResult(result: ImportGraphResult): void {
+ *   if (result.errors.length > 0) {
+ *     console.warn('Some imports could not be resolved:', result.errors);
+ *   }
+ *   console.log(`Found ${result.files.length} files from ${result.entries.length} entries`);
+ * }
+ * ```
  *
  * @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;
+export declare interface ImportGraphResult {
+    /**
+     * All TypeScript source files reachable from the entry points.
+     *
+     * @remarks
+     * Paths are absolute, normalized, and sorted alphabetically.
+     * Test files (`.test.ts`, `.spec.ts`) and test directories (`__test__`, `__tests__`)
+     * are automatically filtered out from results.
+     */
+    files: string[];
+    /**
+     * The entry points that were traced.
+     *
+     * @remarks
+     * Paths are absolute and normalized. These are the starting points
+     * from which the import graph was traversed.
+     */
+    entries: string[];
+    /**
+     * Errors encountered during import graph analysis.
+     *
+     * @remarks
+     * These errors are non-fatal: tracing continues despite individual failures.
+     * Common errors include missing entry files, unresolvable imports,
+     * or tsconfig parsing failures.
+     *
+     * Each error includes a `type` field for programmatic handling and
+     * a human-readable `message`. Some errors also include a `path` field
+     * indicating the relevant file.
+     */
+    errors: ImportGraphError[];
+}
 
 /**
+ * Builder for Node.js ESM libraries using RSlib.
+ *
+ * @remarks
+ * 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
- * Node library builder class
  */
 export declare class NodeLibraryBuilder {
     static DEFAULT_OPTIONS: NodeLibraryBuilderOptions;
@@ -518,9 +947,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 +967,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 +986,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 +1017,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 +1042,249 @@ 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
+     * 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';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   apiModel: {
+     *     enabled: true,
+     *     filename: 'my-package.api.json',
+     *   },
+     * });
+     * ```
+     */
+    apiModel?: ApiModelOptions | boolean;
+    /**
+     * Options for TSDoc lint validation.
+     * When enabled, validates TSDoc comments before the build starts.
+     *
+     * @remarks
+     * Uses ESLint with `eslint-plugin-tsdoc` to validate TSDoc syntax.
+     * By default, throws errors in CI environments and logs errors locally.
+     * The generated `tsdoc.json` config is persisted locally for IDE integration.
+     *
+     * @example
+     * Enable with defaults (throws in CI, errors locally):
+     * ```typescript
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   tsdocLint: true,
+     * });
+     * ```
+     *
+     * @example
+     * Enable with custom configuration:
      * ```typescript
-     * // Enable API model generation with defaults
-     * NodeLibraryBuilder.create({
-     *   apiModel: true,
-     * })
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
      *
-     * // Enable with custom filename
-     * NodeLibraryBuilder.create({
-     *   apiModel: {
-     *     enabled: true,
-     *     filename: "my-package.api.json",
+     * export default NodeLibraryBuilder.create({
+     *   tsdocLint: {
+     *     tsdoc: {
+     *       tagDefinitions: [{ tagName: '@error', syntaxKind: 'block' }],
+     *     },
+     *     onError: 'throw',
+     *     persistConfig: true,
      *   },
-     * })
+     * });
      * ```
      */
-    apiModel?: ApiModelOptions | boolean;
+    tsdocLint?: TsDocLintPluginOptions | 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 +1293,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 {
@@ -961,6 +1406,168 @@ export declare class TsDocConfigBuilder {
     private static syntaxKindToString;
 }
 
+/**
+ * Error behavior for TSDoc lint errors.
+ *
+ * @remarks
+ * - `"warn"`: Log warnings but continue the build
+ * - `"error"`: Log errors but continue the build
+ * - `"throw"`: Fail the build with an error
+ *
+ * @public
+ */
+export declare type TsDocLintErrorBehavior = "warn" | "error" | "throw";
+
+/**
+ * Creates a plugin to validate TSDoc comments before build using ESLint with eslint-plugin-tsdoc.
+ *
+ * @remarks
+ * This plugin runs TSDoc validation during the `onBeforeBuild` hook, ensuring that
+ * documentation errors are caught before compilation begins. It generates a virtual
+ * `tsdoc.json` configuration file that can be persisted for IDE and tool integration.
+ *
+ * ## Features
+ *
+ * - Programmatic ESLint execution with `eslint-plugin-tsdoc`
+ * - Configurable error handling (warn, error, throw)
+ * - Automatic CI detection for stricter defaults
+ * - Optional tsdoc.json persistence for tool integration
+ * - Automatic file discovery via import graph analysis
+ * - Customizable file patterns when needed
+ *
+ * ## Error Handling
+ *
+ * | Environment | Default Behavior | On Lint Errors |
+ * |-------------|------------------|----------------|
+ * | Local       | `"error"`        | Log and continue |
+ * | CI          | `"throw"`        | Fail the build |
+ *
+ * ## Required Dependencies
+ *
+ * This plugin requires the following optional peer dependencies:
+ * - `eslint`
+ * - `@typescript-eslint/parser`
+ * - `eslint-plugin-tsdoc`
+ *
+ * Install with: `pnpm add -D eslint @typescript-eslint/parser eslint-plugin-tsdoc`
+ *
+ * @param options - Plugin configuration options
+ * @returns An Rsbuild plugin that validates TSDoc comments before the build
+ *
+ * @example
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     TsDocLintPlugin({
+ *       onError: 'throw',
+ *       persistConfig: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const TsDocLintPlugin: (options?: TsDocLintPluginOptions) => RsbuildPlugin;
+
+/**
+ * Options for the TSDoc lint plugin.
+ *
+ * @remarks
+ * This plugin validates TSDoc comments in your source files before the build
+ * starts using ESLint with `eslint-plugin-tsdoc`. It helps catch documentation
+ * errors early in the development cycle.
+ *
+ * @example
+ * Enable with defaults (throws in CI, errors locally):
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [TsDocLintPlugin()],
+ * });
+ * ```
+ *
+ * @example
+ * Custom configuration:
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     TsDocLintPlugin({
+ *       tsdoc: {
+ *         tagDefinitions: [{ tagName: '@error', syntaxKind: 'block' }],
+ *       },
+ *       onError: 'throw',
+ *       persistConfig: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare interface TsDocLintPluginOptions {
+    /**
+     * Whether to enable TSDoc linting.
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * TSDoc configuration for custom tag definitions.
+     * Uses the same options as the DtsPlugin's apiModel.tsdoc option.
+     *
+     * @remarks
+     * By default, all standard tag groups (core, extended, discretionary) are
+     * enabled. Custom tags defined in `tagDefinitions` are automatically
+     * supported.
+     */
+    tsdoc?: TsDocOptions;
+    /**
+     * Override automatic file discovery with explicit file paths or glob patterns.
+     *
+     * @remarks
+     * By default, TsDocLintPlugin uses import graph analysis to discover files
+     * from your package's exports. This ensures only public API files are linted.
+     *
+     * Use this option only when you need to lint specific files that aren't
+     * part of the export graph, or to override the automatic discovery.
+     *
+     * When specified as glob patterns, test files and `__test__` directories
+     * are still excluded unless explicitly included.
+     *
+     * @example
+     * ```typescript
+     * // Explicit patterns override automatic discovery
+     * TsDocLintPlugin({
+     *   include: ["src/**\/*.ts", "!**\/*.test.ts"],
+     * })
+     * ```
+     */
+    include?: string[];
+    /**
+     * How to handle TSDoc lint errors.
+     * - `"warn"`: Log warnings but continue the build
+     * - `"error"`: Log errors but continue the build
+     * - `"throw"`: Fail the build with an error
+     *
+     * @defaultValue `"throw"` in CI environments, `"error"` locally
+     */
+    onError?: TsDocLintErrorBehavior;
+    /**
+     * 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 linting
+     *
+     * @defaultValue `true` when not in CI, `false` in CI environments
+     */
+    persistConfig?: boolean | PathLike;
+}
+
 /**
  * Options for tsdoc-metadata.json generation.
  * @public
@@ -1016,10 +1623,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 +1637,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 +1663,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 +1684,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";