@savvy-web/rslib-builder 0.3.0 → 0.5.0

package/index.d.ts

@@ -40,12 +40,11 @@
  */
 
 import type { ConfigParams } from '@rslib/core';
-import type { PackageJson } from 'type-fest';
 import type { PathLike } from 'node:fs';
-import type { RawCopyPattern } from '@rspack/binding';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RslibConfig } from '@rslib/core';
 import type { SourceConfig } from '@rsbuild/core';
+import ts from 'typescript';
 
 /**
  * Options for API model generation.
@@ -227,6 +226,52 @@ export declare interface AutoEntryPluginOptions {
  */
 export declare type BuildTarget = "dev" | "npm";
 
+/**
+ * Configuration for copying files during the build process.
+ *
+ * @remarks
+ * This interface mirrors rspack's copy pattern configuration and is passed directly
+ * to the rspack CopyPlugin. All properties except `from` are optional.
+ *
+ * @example
+ * ```typescript
+ * // Copy a directory
+ * { from: "./public", to: "./", context: process.cwd() }
+ *
+ * // Copy specific files
+ * { from: "**\/*.json", to: "./config" }
+ * ```
+ *
+ * @public
+ */
+export declare interface CopyPatternConfig {
+    /** Source path or glob pattern to copy from */
+    from: string;
+    /** Destination path (relative to output directory) */
+    to?: string;
+    /** Base directory for resolving `from` path */
+    context?: string;
+    /** Type of destination: "dir", "file", or "template" */
+    toType?: "dir" | "file" | "template";
+    /** If true, does not emit an error if the source is missing */
+    noErrorOnMissing?: boolean;
+    /** Glob options for pattern matching */
+    globOptions?: {
+        /** Patterns to ignore */
+        ignore?: string[];
+        /** Whether to match dotfiles */
+        dot?: boolean;
+    };
+    /** Filter function to include/exclude files */
+    filter?: (filepath: string) => boolean | Promise<boolean>;
+    /** Transform function to modify file contents */
+    transform?: {
+        transformer: (input: Buffer, absoluteFilename: string) => string | Buffer | Promise<string> | Promise<Buffer>;
+    } | ((input: Buffer, absoluteFilename: string) => string | Buffer | Promise<string> | Promise<Buffer>);
+    /** Priority for conflicting files (higher = higher priority) */
+    priority?: number;
+}
+
 /**
  * Plugin to generate TypeScript declaration files using tsgo and emit them through Rslib's asset pipeline.
  *
@@ -458,6 +503,439 @@ export declare interface FilesArrayPluginOptions<TTarget extends string = string
     target: TTarget;
 }
 
+/**
+ * Analyzes TypeScript import relationships to discover all files
+ * reachable from specified entry points.
+ *
+ * @remarks
+ * 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
+ * import { ImportGraph } from '@savvy-web/rslib-builder';
+ *
+ * // 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() }
+ * );
+ * ```
+ *
+ * @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 ImportGraph {
+    private readonly options;
+    private readonly sys;
+    private program;
+    private compilerOptions;
+    private moduleResolutionCache;
+    constructor(options: ImportGraphOptions);
+    /**
+     * Trace all imports from the given entry points.
+     *
+     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
+     * @returns Deduplicated list of all reachable TypeScript files
+     */
+    traceFromEntries(entryPaths: string[]): ImportGraphResult;
+    /**
+     * 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
+     */
+    traceFromPackageExports(packageJsonPath: string): ImportGraphResult;
+    /**
+     * Initialize the TypeScript program for module resolution.
+     */
+    private initializeProgram;
+    /**
+     * Find tsconfig.json path.
+     */
+    private findTsConfig;
+    /**
+     * Resolve entry path to absolute path.
+     */
+    private resolveEntryPath;
+    /**
+     * Recursively trace imports from a source file.
+     */
+    private traceImports;
+    /**
+     * Extract all import/export module specifiers from a source file.
+     */
+    private extractImports;
+    /**
+     * Resolve a module specifier to an absolute file path.
+     */
+    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;
+}
+
+/**
+ * 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 ImportGraphError {
+    /**
+     * The type of error that occurred.
+     *
+     * @remarks
+     * Use this field for programmatic error handling to distinguish
+     * between different failure modes.
+     */
+    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;
+}
+
+/**
+ * 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 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 ImportGraphOptions {
+    /**
+     * 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`.
+     */
+    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[];
+}
+
+/**
+ * Result of import graph analysis.
+ *
+ * @remarks
+ * 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 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[];
+}
+
+/**
+ * Matches a JSON array.
+ *
+ * @public
+ */
+export declare type JsonArray = JsonValue[] | readonly JsonValue[];
+
+/**
+ * Matches a JSON object.
+ *
+ * @remarks
+ * This type can be useful to enforce some input to be JSON-compatible or as a
+ * super-type to be extended from.
+ *
+ * @public
+ */
+export declare type JsonObject = {
+    [Key in string]: JsonValue;
+};
+
+/**
+ * Package.json type definitions.
+ *
+ * @remarks
+ * This is a local copy of type-fest's PackageJson types with TSDoc fixes.
+ * Original source: https://github.com/sindresorhus/type-fest
+ *
+ * TSDoc fixes applied:
+ * - Added deprecation messages to `@deprecated` tags
+ * - Fixed code fence formatting in `packageManager` docs
+ *
+ */
+/**
+ * Matches any valid JSON primitive value.
+ *
+ * @public
+ */
+export declare type JsonPrimitive = string | number | boolean | null;
+
+/**
+ * Matches any valid JSON value.
+ *
+ * @public
+ */
+export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/**
+ * Allows creating a union type by combining primitive types and literal types
+ * without sacrificing auto-completion in IDEs for the literal type part of the union.
+ *
+ * @remarks
+ * Currently, when a union type of a primitive type is combined with literal types,
+ * TypeScript loses all information about the combined literals. Thus, when such
+ * type is used in an IDE with autocompletion, no suggestions are made for the
+ * declared literals.
+ *
+ * This type is a workaround for Microsoft/TypeScript#29729.
+ *
+ * @typeParam LiteralType - The literal type(s) to include
+ * @typeParam BaseType - The base primitive type
+ *
+ * @public
+ */
+declare type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+
 /**
  * Builder for Node.js ESM libraries using RSlib.
  *
@@ -560,7 +1038,7 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     exportsAsIndexes?: boolean;
-    copyPatterns: (string | (Pick<RawCopyPattern, "from"> & Partial<Omit<RawCopyPattern, "from">>))[];
+    copyPatterns: (string | CopyPatternConfig)[];
     /** Additional plugins */
     plugins: RsbuildPlugin[];
     define: SourceConfig["define"];
@@ -696,8 +1174,471 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     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
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   tsdocLint: {
+     *     tsdoc: {
+     *       tagDefinitions: [{ tagName: '@error', syntaxKind: 'block' }],
+     *     },
+     *     onError: 'throw',
+     *     persistConfig: true,
+     *   },
+     * });
+     * ```
+     */
+    tsdocLint?: TsDocLintPluginOptions | boolean;
 }
 
+/**
+ * PackageJson namespace containing all sub-types.
+ *
+ * @public
+ */
+export declare namespace PackageJson {
+    /**
+     * A person who has been involved in creating or maintaining the package.
+     */
+    export type Person = string | {
+        name: string;
+        url?: string;
+        email?: string;
+    };
+    /**
+     * Location for reporting bugs.
+     */
+    export type BugsLocation = string | {
+        /** The URL to the package's issue tracker. */
+        url?: string;
+        /** The email address to which issues should be reported. */
+        email?: string;
+    };
+    /**
+     * Directory locations within the package.
+     */
+    export interface DirectoryLocations {
+        [directoryType: string]: JsonValue | undefined;
+        /** Location for executable scripts. Sugar to generate entries in the `bin` property by walking the folder. */
+        bin?: string;
+        /** Location for Markdown files. */
+        doc?: string;
+        /** Location for example scripts. */
+        example?: string;
+        /** Location for the bulk of the library. */
+        lib?: string;
+        /** Location for man pages. Sugar to generate a `man` array by walking the folder. */
+        man?: string;
+        /** Location for test files. */
+        test?: string;
+    }
+    /**
+     * Script commands that are run at various times in the lifecycle of the package.
+     */
+    export type Scripts = {
+        /** Run before the package is published (Also run on local `npm install` without any arguments). */
+        prepublish?: string;
+        /** Run both before the package is packed and published, and on local `npm install` without any arguments. */
+        prepare?: string;
+        /** Run before the package is prepared and packed, only on `npm publish`. */
+        prepublishOnly?: string;
+        /** Run before a tarball is packed (on `npm pack`, `npm publish`, and when installing git dependencies). */
+        prepack?: string;
+        /** Run after the tarball has been generated and moved to its final destination. */
+        postpack?: string;
+        /** Run after the package is published. */
+        publish?: string;
+        /** Run after the package is published. */
+        postpublish?: string;
+        /** Run before the package is installed. */
+        preinstall?: string;
+        /** Run after the package is installed. */
+        install?: string;
+        /** Run after the package is installed and after `install`. */
+        postinstall?: string;
+        /** Run before the package is uninstalled and before `uninstall`. */
+        preuninstall?: string;
+        /** Run before the package is uninstalled. */
+        uninstall?: string;
+        /** Run after the package is uninstalled. */
+        postuninstall?: string;
+        /** Run before bump the package version and before `version`. */
+        preversion?: string;
+        /** Run before bump the package version. */
+        version?: string;
+        /** Run after bump the package version. */
+        postversion?: string;
+        /** Run with the `npm test` command, before `test`. */
+        pretest?: string;
+        /** Run with the `npm test` command. */
+        test?: string;
+        /** Run with the `npm test` command, after `test`. */
+        posttest?: string;
+        /** Run with the `npm stop` command, before `stop`. */
+        prestop?: string;
+        /** Run with the `npm stop` command. */
+        stop?: string;
+        /** Run with the `npm stop` command, after `stop`. */
+        poststop?: string;
+        /** Run with the `npm start` command, before `start`. */
+        prestart?: string;
+        /** Run with the `npm start` command. */
+        start?: string;
+        /** Run with the `npm start` command, after `start`. */
+        poststart?: string;
+        /** Run with the `npm restart` command, before `restart`. */
+        prerestart?: string;
+        /** Run with the `npm restart` command. */
+        restart?: string;
+        /** Run with the `npm restart` command, after `restart`. */
+        postrestart?: string;
+    } & Partial<Record<string, string>>;
+    /**
+     * Dependencies of the package. The version range is a string which has one or
+     * more space-separated descriptors.
+     */
+    export type Dependency = Partial<Record<string, string>>;
+    /**
+     * Recursive map describing selective dependency version overrides supported by npm.
+     */
+    export type DependencyOverrides = {
+        [packageName in string]: string | undefined | DependencyOverrides;
+    };
+    /**
+     * Specifies requirements for development environment components.
+     */
+    export interface DevEngineDependency {
+        name: string;
+        version?: string;
+        onFail?: "ignore" | "warn" | "error" | "download";
+    }
+    /**
+     * A mapping of conditions and the paths to which they resolve.
+     */
+    export interface ExportConditions {
+        [condition: string]: Exports;
+    }
+    /**
+     * Entry points of a module, optionally with conditions and subpath exports.
+     */
+    export type Exports = null | string | Array<string | ExportConditions> | ExportConditions;
+    /**
+     * Import map entries of a module, optionally with conditions and subpath imports.
+     */
+    export interface Imports {
+        [key: `#${string}`]: Exports;
+    }
+    /**
+     * Non-standard entry point fields used by various bundlers.
+     */
+    export interface NonStandardEntryPoints {
+        /** An ECMAScript module ID that is the primary entry point to the program. */
+        module?: string;
+        /** A module ID with untranspiled code that is the primary entry point to the program. */
+        esnext?: string | {
+            [moduleName: string]: string | undefined;
+            main?: string;
+            browser?: string;
+        };
+        /** A hint to JavaScript bundlers or component tools when packaging modules for client side use. */
+        browser?: string | Partial<Record<string, string | false>>;
+        /**
+         * Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused.
+         *
+         * @see {@link https://webpack.js.org/guides/tree-shaking/ | Webpack Tree Shaking}
+         */
+        sideEffects?: boolean | string[];
+    }
+    /**
+     * TypeScript-specific configuration fields.
+     */
+    export interface TypeScriptConfiguration {
+        /** Location of the bundled TypeScript declaration file. */
+        types?: string;
+        /** Version selection map of TypeScript. */
+        typesVersions?: Partial<Record<string, Partial<Record<string, string[]>>>>;
+        /** Location of the bundled TypeScript declaration file. Alias of `types`. */
+        typings?: string;
+    }
+    /**
+     * An alternative configuration for workspaces.
+     */
+    export interface WorkspaceConfig {
+        /** An array of workspace pattern strings which contain the workspace packages. */
+        packages?: WorkspacePattern[];
+        /**
+         * Designed to solve the problem of packages which break when their `node_modules`
+         * are moved to the root workspace directory - a process known as hoisting.
+         *
+         * @see {@link https://classic.yarnpkg.com/blog/2018/02/15/nohoist/ | Yarn nohoist}
+         */
+        nohoist?: WorkspacePattern[];
+    }
+    /**
+     * A workspace pattern points to a directory or group of directories which
+     * contain packages that should be included in the workspace installation process.
+     *
+     * @example
+     * `docs` - Include the docs directory and install its dependencies.
+     *
+     * @example
+     * `packages/*` - Include all nested directories within the packages directory.
+     */
+    export type WorkspacePattern = string;
+    /**
+     * Yarn-specific configuration fields.
+     */
+    export interface YarnConfiguration {
+        /**
+         * If your package only allows one version of a given dependency, and you'd like
+         * to enforce the same behavior as `yarn install --flat` on the command-line,
+         * set this to `true`.
+         */
+        flat?: boolean;
+        /** Selective version resolutions. Allows the definition of custom package versions inside dependencies. */
+        resolutions?: Dependency;
+    }
+    /**
+     * JSPM-specific configuration fields.
+     */
+    export interface JSPMConfiguration {
+        /** JSPM configuration. */
+        jspm?: PackageJson;
+    }
+    /**
+     * Publish configuration options.
+     */
+    export interface PublishConfig {
+        /** Additional properties from the npm docs on `publishConfig`. */
+        [additionalProperties: string]: JsonValue | undefined;
+        /**
+         * When publishing scoped packages, the access level defaults to restricted.
+         * If you want your scoped package to be publicly viewable set `--access=public`.
+         */
+        access?: "public" | "restricted";
+        /**
+         * The base URL of the npm registry.
+         *
+         * @defaultValue `'https://registry.npmjs.org/'`
+         */
+        registry?: string;
+        /**
+         * The tag to publish the package under.
+         *
+         * @defaultValue `'latest'`
+         */
+        tag?: string;
+    }
+    /**
+     * Type for npm's `package.json` file containing standard npm properties.
+     *
+     * @see {@link https://docs.npmjs.com/creating-a-package-json-file | npm docs}
+     */
+    export interface PackageJsonStandard {
+        /** The name of the package. */
+        name?: string;
+        /** Package version, parseable by `node-semver`. */
+        version?: string;
+        /** Package description, listed in `npm search`. */
+        description?: string;
+        /** Keywords associated with package, listed in `npm search`. */
+        keywords?: string[];
+        /** The URL to the package's homepage. */
+        homepage?: LiteralUnion<".", string>;
+        /** The URL to the package's issue tracker and/or the email address to which issues should be reported. */
+        bugs?: BugsLocation;
+        /** The license for the package. */
+        license?: string;
+        /** The licenses for the package. */
+        licenses?: Array<{
+            type?: string;
+            url?: string;
+        }>;
+        /** The author of the package. */
+        author?: Person;
+        /** A list of people who contributed to the package. */
+        contributors?: Person[];
+        /** A list of people who maintain the package. */
+        maintainers?: Person[];
+        /** The files included in the package. */
+        files?: string[];
+        /**
+         * Resolution algorithm for importing ".js" files from the package's scope.
+         *
+         * @see {@link https://nodejs.org/api/esm.html#esm_package_json_type_field | Node.js ESM docs}
+         */
+        type?: "module" | "commonjs";
+        /** The module ID that is the primary entry point to the program. */
+        main?: string;
+        /**
+         * Subpath exports to define entry points of the package.
+         *
+         * @see {@link https://nodejs.org/api/packages.html#subpath-exports | Node.js Subpath exports}
+         */
+        exports?: Exports;
+        /**
+         * Subpath imports to define internal package import maps.
+         *
+         * @see {@link https://nodejs.org/api/packages.html#subpath-imports | Node.js Subpath imports}
+         */
+        imports?: Imports;
+        /** The executable files that should be installed into the `PATH`. */
+        bin?: string | Partial<Record<string, string>>;
+        /** Filenames to put in place for the `man` program to find. */
+        man?: string | string[];
+        /** Indicates the structure of the package. */
+        directories?: DirectoryLocations;
+        /** Location for the code repository. */
+        repository?: string | {
+            type: string;
+            url: string;
+            /** Relative path to package.json if it is placed in non-root directory (for monorepos). */
+            directory?: string;
+        };
+        /** Script commands that are run at various times in the lifecycle of the package. */
+        scripts?: Scripts;
+        /** Is used to set configuration parameters used in package scripts that persist across upgrades. */
+        config?: JsonObject;
+        /** The dependencies of the package. */
+        dependencies?: Dependency;
+        /** Additional tooling dependencies that are not required for the package to work. */
+        devDependencies?: Dependency;
+        /** Dependencies that are skipped if they fail to install. */
+        optionalDependencies?: Dependency;
+        /** Dependencies that will usually be required by the package user directly or via another dependency. */
+        peerDependencies?: Dependency;
+        /** Indicate peer dependencies that are optional. */
+        peerDependenciesMeta?: Partial<Record<string, {
+            optional: true;
+        }>>;
+        /** Package names that are bundled when the package is published. */
+        bundledDependencies?: string[];
+        /** Alias of `bundledDependencies`. */
+        bundleDependencies?: string[];
+        /** Overrides is used to support selective version overrides using npm. */
+        overrides?: DependencyOverrides;
+        /** Engines that this package runs on. */
+        engines?: {
+            [EngineName in "npm" | "node" | string]?: string;
+        };
+        /**
+         * Whether to enforce engine requirements strictly.
+         *
+         * @deprecated This field is no longer used by npm. Use the `engine-strict` npm config instead.
+         */
+        engineStrict?: boolean;
+        /** Operating systems the module runs on. */
+        os?: Array<LiteralUnion<"aix" | "darwin" | "freebsd" | "linux" | "openbsd" | "sunos" | "win32" | "!aix" | "!darwin" | "!freebsd" | "!linux" | "!openbsd" | "!sunos" | "!win32", string>>;
+        /** CPU architectures the module runs on. */
+        cpu?: Array<LiteralUnion<"arm" | "arm64" | "ia32" | "mips" | "mipsel" | "ppc" | "ppc64" | "s390" | "s390x" | "x32" | "x64" | "!arm" | "!arm64" | "!ia32" | "!mips" | "!mipsel" | "!ppc" | "!ppc64" | "!s390" | "!s390x" | "!x32" | "!x64", string>>;
+        /** Define the runtime and package manager for developing the current project. */
+        devEngines?: {
+            os?: DevEngineDependency | DevEngineDependency[];
+            cpu?: DevEngineDependency | DevEngineDependency[];
+            libc?: DevEngineDependency | DevEngineDependency[];
+            runtime?: DevEngineDependency | DevEngineDependency[];
+            packageManager?: DevEngineDependency | DevEngineDependency[];
+        };
+        /**
+         * If set to `true`, a warning will be shown if package is installed locally.
+         *
+         * @deprecated This field is no longer used by npm. Use the `bin` field to create CLI tools instead.
+         */
+        preferGlobal?: boolean;
+        /** If set to `true`, then npm will refuse to publish it. */
+        private?: boolean;
+        /** A set of config values that will be used at publish-time. */
+        publishConfig?: PublishConfig;
+        /**
+         * Describes and notifies consumers of a package's monetary support information.
+         *
+         * @see {@link https://github.com/npm/rfcs/blob/main/implemented/0017-add-funding-support.md | npm funding RFC}
+         */
+        funding?: string | {
+            /** The type of funding. */
+            type?: LiteralUnion<"github" | "opencollective" | "patreon" | "individual" | "foundation" | "corporation", string>;
+            /** The URL to the funding page. */
+            url: string;
+        };
+        /**
+         * Used to configure npm workspaces / Yarn workspaces.
+         *
+         * @remarks
+         * Workspaces allow you to manage multiple packages within the same repository
+         * in such a way that you only need to run your install command once in order
+         * to install all of them in a single pass.
+         *
+         * Please note that the top-level `private` property of `package.json` must
+         * be set to `true` in order to use workspaces.
+         *
+         * @see {@link https://docs.npmjs.com/cli/using-npm/workspaces | npm workspaces}
+         * @see {@link https://classic.yarnpkg.com/docs/workspaces/ | Yarn workspaces}
+         */
+        workspaces?: WorkspacePattern[] | WorkspaceConfig;
+    }
+    /**
+     * Type for `package.json` file used by the Node.js runtime.
+     *
+     * @see {@link https://nodejs.org/api/packages.html#nodejs-packagejson-field-definitions | Node.js docs}
+     */
+    export interface NodeJsStandard {
+        /**
+         * Defines which package manager is expected to be used when working on the current project.
+         *
+         * @remarks
+         * It can be set to any of the supported package managers, and will ensure that
+         * your teams use the exact same package manager versions without having to
+         * install anything else other than Node.js.
+         *
+         * This field is currently experimental and needs to be opted-in; check the
+         * Corepack page for details about the procedure.
+         *
+         * @example
+         * ```json
+         * {
+         *   "packageManager": "pnpm@8.0.0"
+         * }
+         * ```
+         *
+         * @see {@link https://nodejs.org/api/corepack.html | Node.js Corepack docs}
+         */
+        packageManager?: string;
+    }
+}
+
+/**
+ * Type for npm's `package.json` file.
+ *
+ * @remarks
+ * Also includes types for fields used by other popular projects, like TypeScript and Yarn.
+ *
+ * @see {@link https://docs.npmjs.com/creating-a-package-json-file | npm docs}
+ *
+ * @public
+ */
+export declare type PackageJson = JsonObject & PackageJson.NodeJsStandard & PackageJson.PackageJsonStandard & PackageJson.NonStandardEntryPoints & PackageJson.TypeScriptConfiguration & PackageJson.YarnConfiguration & PackageJson.JSPMConfiguration;
+
 /**
  * Plugin to transform package.json for distribution.
  *
@@ -849,6 +1790,15 @@ export declare interface PackageJsonTransformPluginOptions {
     transform?: (pkg: PackageJson) => PackageJson;
 }
 
+/**
+ * Matches any primitive value.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Glossary/Primitive | MDN Primitive}
+ *
+ * @public
+ */
+declare type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+
 /**
  * Async RSLib configuration function type.
  * @public
@@ -1001,6 +1951,166 @@ 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 |
+ *
+ * ## Dependencies
+ *
+ * This plugin uses ESLint programmatically with the following packages:
+ * - `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
@@ -1096,6 +2206,11 @@ export declare interface TsDocOptions {
      * TSDoc warnings include unknown tags, malformed syntax, and other
      * documentation issues detected by API Extractor during processing.
      *
+     * **Important:** This setting only applies to first-party warnings (from your
+     * project's source code). Third-party warnings from dependencies in
+     * `node_modules/` are always logged but never fail the build, since they
+     * cannot be fixed by the consuming project.
+     *
      * @defaultValue `"fail"` in CI environments (`CI` or `GITHUB_ACTIONS` env vars),
      *               `"log"` otherwise
      */