@savvy-web/rslib-builder 0.1.0

package/index.d.ts

@@ -0,0 +1,855 @@
+/**
+ * RSLib-based build system for Node.js libraries with automatic package.json transformation,
+ * TypeScript declaration bundling, and multi-target support.
+ *
+ * @remarks
+ * This package provides a powerful builder system built on top of RSLib that simplifies the
+ * process of building modern ESM Node.js libraries. It offers:
+ *
+ * - **Automatic Entry Detection**: Auto-detects entry points from package.json exports
+ * - **Multi-Target Builds**: Support for dev and npm build targets
+ * - **Bundled ESM Output**: Optimized single-file outputs with rolled-up types
+ * - **Package.json Transformation**: Automatic path updates, PNPM catalog resolution
+ * - **TypeScript Declaration Bundling**: Using tsgo and API Extractor
+ * - **File Array Generation**: Automatic files array creation for package.json
+ * - **API Model Generation**: Optional api.model.json for documentation tooling
+ *
+ * @example
+ * Basic usage in rslib.config.ts:
+ * ```typescript
+ * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+ *
+ * export default NodeLibraryBuilder.create({});
+ * ```
+ *
+ * @example
+ * With custom transformations:
+ * ```typescript
+ * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+ *
+ * export default NodeLibraryBuilder.create({
+ *   externals: ['@rslib/core'],
+ *   transform({ pkg }) {
+ *     delete pkg.devDependencies;
+ *     return pkg;
+ *   }
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { ConfigParams } from '@rslib/core';
+import type { PackageJson } from 'type-fest';
+import type { RawCopyPattern } from '@rspack/binding';
+import type { RsbuildPlugin } from '@rsbuild/core';
+import type { RslibConfig } from '@rslib/core';
+import type { SourceConfig } from '@rsbuild/core';
+
+/**
+ * Options for API model generation.
+ * When enabled, generates an api.model.json file using API Extractor.
+ *
+ * @remarks
+ * API models are only generated for the main "index" entry point (the "." export).
+ * Additional entry points like "./hooks" or "./utils" do not generate separate API models.
+ * This prevents multiple conflicting API models and ensures a single source of truth
+ * for package documentation.
+ *
+ * @public
+ */
+export declare interface ApiModelOptions {
+    /**
+     * Whether to enable API model generation.
+     * @defaultValue false
+     */
+    enabled?: boolean;
+    /**
+     * Filename for the generated API model file.
+     * @defaultValue "api.model.json"
+     */
+    filename?: string;
+    /**
+     * Whether to add a .npmignore file that excludes the API model file.
+     * This is useful when the API model is for internal tooling only.
+     * @defaultValue true
+     */
+    npmIgnore?: boolean;
+    /**
+     * Local paths to copy the API model and package.json to.
+     * Used for local testing with documentation systems.
+     *
+     * @remarks
+     * Each path must be a directory. The parent directory must exist,
+     * but the final directory will be created if it doesn't exist.
+     * Both api.model.json and the processed package.json will be copied.
+     *
+     * @example
+     * ```typescript
+     * apiModel: {
+     *   enabled: true,
+     *   localPaths: ["../docs-site/lib/packages/my-package"],
+     * }
+     * ```
+     */
+    localPaths?: string[];
+}
+
+/**
+ * Plugin to read package.json and configure entry points based on exports.
+ *
+ * @param options - Plugin configuration options
+ * @param options.exportsAsIndexes - When true, export paths create index files in nested directories
+ * @public
+ */
+export declare const AutoEntryPlugin: (options?: {
+    exportsAsIndexes?: boolean | undefined;
+} | undefined) => RsbuildPlugin;
+
+/**
+ * @public
+ */
+export declare type BuildTarget = "dev" | "npm";
+
+/**
+ * Recursively collects all .d.ts and .d.ts.map files from a directory.
+ *
+ * @public
+ */
+export declare function collectDtsFiles(dir: string, baseDir?: string): Promise<Array<{
+    path: string;
+    relativePath: string;
+}>>;
+
+/**
+ * Plugin to generate TypeScript declaration files using tsgo and emit them through Rslib's asset pipeline.
+ *
+ * @remarks
+ * This plugin uses tsgo (@typescript/native-preview) for faster declaration file generation
+ * and integrates with Rslib's build system by emitting generated files as compilation assets.
+ *
+ * ## Features
+ *
+ * - Uses tsgo exclusively for .d.ts generation (faster than tsc)
+ * - Emits .d.ts and .d.ts.map files through Rslib's asset pipeline
+ * - Optional bundling with API Extractor for rollup mode
+ * - Supports watch mode
+ * - Integrates seamlessly with other Rslib plugins
+ * - Respects tsconfig.json settings
+ *
+ * ## Build Workflow
+ *
+ * 1. **Config Phase** (`modifyRsbuildConfig`):
+ *    - Finds and loads tsconfig.json
+ *    - Creates temp directory for .d.ts generation
+ *    - Validates configuration
+ *
+ * 2. **Asset Processing Phase** (`processAssets`):
+ *    - Cleans temp directory at start of build (to remove stale files)
+ *    - Spawns tsgo to generate .d.ts files to temp directory
+ *    - Recursively collects all generated .d.ts and .d.ts.map files
+ *    - If bundling: uses API Extractor to bundle declarations per entry point
+ *    - Emits files through compilation.emitAsset()
+ *    - Adds .d.ts files (not .d.ts.map) to the files array for npm publishing
+ *    - Preserves temp directory after build for API Extractor documentation generation
+ *
+ * @param options - Plugin configuration options
+ *
+ * @example
+ * ```typescript
+ * import { DtsPlugin } from "@savvy-web/shared/rslib";
+ *
+ * export default {
+ *   plugins: [
+ *     DtsPlugin({
+ *       abortOnError: true,
+ *       bundle: true,
+ *       bundledPackages: ['type-fest', '@commitlint/*']
+ *     })
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare const DtsPlugin: (options?: DtsPluginOptions) => RsbuildPlugin;
+
+/**
+ * Options for configuring the DTS plugin.
+ * @public
+ */
+export declare interface DtsPluginOptions {
+    /**
+     * Path to TypeScript configuration file.
+     * If not specified, uses the tsconfigPath from Rsbuild config or searches for tsconfig.json.
+     */
+    tsconfigPath?: string;
+    /**
+     * Custom output directory for declaration files relative to dist root.
+     * If not specified, uses the declarationDir from tsconfig.json or falls back to dist root.
+     */
+    distPath?: string;
+    /**
+     * Whether to abort the build on TypeScript errors.
+     * @defaultValue true
+     */
+    abortOnError?: boolean;
+    /**
+     * Custom file extension for declaration files.
+     * @defaultValue ".d.ts"
+     */
+    dtsExtension?: string;
+    /**
+     * Whether to bundle declaration files using API Extractor.
+     * When true, generates a single .d.ts file per entry point.
+     * @defaultValue false
+     */
+    bundle?: boolean;
+    /**
+     * Packages whose types should be bundled (inlined) into the output .d.ts files.
+     * Only applies when bundle is true.
+     * Supports glob patterns (e.g., '@commitlint/*', 'type-fest')
+     * @defaultValue []
+     */
+    bundledPackages?: string[];
+    /**
+     * Banner text to add at the top of bundled declaration files.
+     * Only applies when bundle is true.
+     */
+    banner?: string;
+    /**
+     * Footer text to add at the bottom of bundled declaration files.
+     * Only applies when bundle is true.
+     */
+    footer?: string;
+    /**
+     * Build target (dev, npm).
+     * Used to generate the correct temp tsconfig when tsconfigPath is not provided.
+     */
+    buildTarget?: "dev" | "npm";
+    /**
+     * Options for API model generation.
+     * When enabled, generates an api.model.json file in the dist directory.
+     * Only applies when bundle is true.
+     */
+    apiModel?: ApiModelOptions | boolean;
+}
+
+/**
+ * Ensures a temp directory exists for declaration file generation.
+ * @internal
+ */
+export declare function ensureTempDeclarationDir(cwd: string, name: string): Promise<string>;
+
+/**
+ * Extracts TypeScript entry points from package.json for build configuration.
+ *
+ * @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" -> "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)
+ *
+ * @example
+ * ```typescript
+ * const extractor = new EntryExtractor();
+ *
+ * const packageJson = {
+ *   exports: {
+ *     ".": "./src/index.ts",
+ *     "./utils": "./src/utils.ts",
+ *   },
+ *   bin: {
+ *     "my-cli": "./src/bin/cli.ts"
+ *   }
+ * };
+ *
+ * const result = extractor.extract(packageJson);
+ * console.log(result.entries);
+ * // {
+ * //   "index": "./src/index.ts",
+ * //   "utils": "./src/utils.ts",
+ * //   "bin/my-cli": "./src/bin/cli.ts"
+ * // }
+ * ```
+ *
+ * @public
+ */
+export declare class EntryExtractor {
+    private readonly options;
+    constructor(options?: EntryExtractorOptions);
+    /**
+     * Extracts entry points from package.json exports and bin fields.
+     *
+     * @param packageJson - The package.json to extract entries from
+     * @returns Object containing the extracted entries
+     */
+    extract(packageJson: PackageJson): ExtractedEntries;
+    /**
+     * Extracts entries from the exports field.
+     */
+    private extractFromExports;
+    /**
+     * Extracts entries from the bin field.
+     */
+    private extractFromBin;
+    /**
+     * Resolves a source path from various export value formats.
+     */
+    private resolveSourcePath;
+    /**
+     * Resolves a path to its TypeScript source equivalent.
+     * Maps /dist/ JavaScript paths back to /src/ TypeScript sources.
+     */
+    private resolveToTypeScript;
+    /**
+     * Checks if a path points to a TypeScript file.
+     */
+    private isTypeScriptFile;
+    /**
+     * Creates an entry name from an export key.
+     */
+    private createEntryName;
+}
+
+/**
+ * Options for entry extraction.
+ * @public
+ */
+export declare interface EntryExtractorOptions {
+    /**
+     * When true, export paths create index files in nested directories.
+     * "./foo/bar" becomes "foo/bar/index" instead of "foo-bar".
+     */
+    exportsAsIndexes?: boolean;
+}
+
+/**
+ * Result of entry extraction.
+ * @public
+ */
+export declare interface ExtractedEntries {
+    /**
+     * Entry name to TypeScript source path mapping.
+     */
+    entries: Record<string, string>;
+}
+
+/**
+ * Plugin to manage the files array in package.json
+ * Adds essential files like package.json, README.md, LICENSE and compiled outputs
+ * Other plugins can use api.useExposed("files-array") to add additional files
+ * @public
+ */
+export declare const FilesArrayPlugin: <TTarget extends string = string>(options?: FilesArrayPluginOptions<TTarget> | undefined) => RsbuildPlugin;
+
+/**
+ * @public
+ */
+export declare interface FilesArrayPluginOptions<TTarget extends string = string> {
+    /**
+     * Optional callback to transform files after they're built but before the files array is finalized.
+     * Called in the additional stage, after all assets are created.
+     */
+    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;
+}
+
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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;
+
+/**
+ * @public
+ * Node library builder class
+ */
+export declare class NodeLibraryBuilder {
+    static DEFAULT_OPTIONS: NodeLibraryBuilderOptions;
+    static mergeOptions(options?: Partial<NodeLibraryBuilderOptions>): NodeLibraryBuilderOptions;
+    /**
+     * Creates an async RSLib configuration function that determines build target from envMode.
+     * This provides a clean API where users don't need to handle environment logic.
+     */
+    static create(options?: Partial<NodeLibraryBuilderOptions>): RslibConfigAsyncFn;
+    /**
+     * Creates a single-target build configuration.
+     * This allows proper plugin isolation per build target.
+     */
+    static createSingleTarget(target: BuildTarget, opts: NodeLibraryBuilderOptions): Promise<RslibConfig>;
+}
+
+/**
+ * @public
+ */
+export declare interface NodeLibraryBuilderOptions {
+    /** Override entry points (optional - will auto-detect from package.json) */
+    entry?: Record<string, string | string[]>;
+    /**
+     * When enabled, each export path will generate an index.js file in a directory
+     * structure matching the export path, rather than using the export name as the filename.
+     *
+     * @example
+     * When `exportsAsIndexes` is `true`, given this package.json configuration:
+     * ```json
+     * {
+     *   "exports": {
+     *     ".": "./src/entrypoint.ts",
+     *     "./foo/bar": "./src/foo/bar.ts",
+     *     "./foo/baz": "./src/foo/baz.ts"
+     *   }
+     * }
+     * ```
+     *
+     * You would get this output file structure:
+     * ```
+     * dist/
+     *   index.js
+     *   foo/
+     *     bar/
+     *       index.js
+     *     baz/
+     *       index.js
+     * ```
+     */
+    exportsAsIndexes?: boolean;
+    copyPatterns: (string | (Pick<RawCopyPattern, "from"> & Partial<Omit<RawCopyPattern, "from">>))[];
+    /** Additional plugins */
+    plugins: RsbuildPlugin[];
+    define: SourceConfig["define"];
+    /** Path to tsconfig for build (default: ./tsconfig.build.json) */
+    tsconfigPath: string | undefined;
+    /** Build targets to include (default: ["dev", "npm"]) */
+    targets?: BuildTarget[];
+    /**
+     * External dependencies that should not be bundled.
+     * These modules will be imported at runtime instead of being included in the bundle.
+     *
+     * @remarks
+     * This is useful for dependencies that are in devDependencies but needed at runtime,
+     * such as build tools that the package uses to build other packages.
+     *
+     * @example
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   externals: ['@rslib/core', '@rsbuild/core']
+     * })
+     * ```
+     */
+    externals?: (string | RegExp)[];
+    /**
+     * Packages whose type declarations should be bundled into the output .d.ts files.
+     *
+     * @remarks
+     * By default, RSlib bundles types from packages in package.json. Use this to explicitly
+     * specify which packages (including transitive dependencies) should have their types bundled.
+     * This is particularly useful for ensuring devDependencies are fully inlined without external imports.
+     *
+     * Supports minimatch patterns (e.g., '@pnpm/**', 'picocolors')
+     *
+     * @example
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   dtsBundledPackages: ['@pnpm/lockfile.types', '@pnpm/types', 'picocolors']
+     * })
+     * ```
+     */
+    dtsBundledPackages?: string[];
+    /**
+     * Optional callback to transform files after they're built but before the files array is finalized.
+     * Useful for copying/renaming files or adding additional files to the build output.
+     *
+     * @param context - Transform context containing compilation context and files set
+     * @param context.compilation - Rspack compilation object with assets
+     * @param context.filesArray - Set of files that will be included in package.json files field
+     * @param context.target - Current build target (dev/npm/jsr)
+     *
+     * @example
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   transformFiles({ compilation, filesArray, target }) {
+     *     // 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: {
+        /** Rspack compilation object with assets */
+        compilation: {
+            assets: Record<string, unknown>;
+        };
+        filesArray: Set<string>;
+        target: BuildTarget;
+    }) => void | Promise<void>;
+    /**
+     * Optional transform function to modify package.json before it's saved.
+     * Called after all standard transformations are applied.
+     *
+     * @param context - Transform context containing the target and package.json
+     * @returns The modified package.json (mutations are also supported)
+     *
+     * @example
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   transform({ target, pkg }) {
+     *     if (target === 'npm') {
+     *       // Mutation approach
+     *       delete pkg.devDependencies;
+     *       delete pkg.scripts;
+     *     }
+     *     return pkg;
+     *   }
+     * })
+     * ```
+     */
+    transform?: TransformPackageJsonFn;
+    /**
+     * Options for API model generation.
+     * When enabled, generates an api.model.json file in the dist directory.
+     * Only applies when target is "npm".
+     *
+     * @remarks
+     * The generated api.model.json file contains the full API documentation
+     * in a machine-readable format for use by documentation generators.
+     * A .npmignore file is also generated to exclude the API model from npm publish.
+     *
+     * @example
+     * ```typescript
+     * // Enable API model generation with defaults
+     * NodeLibraryBuilder.create({
+     *   apiModel: true,
+     * })
+     *
+     * // Enable with custom filename
+     * NodeLibraryBuilder.create({
+     *   apiModel: {
+     *     enabled: true,
+     *     filename: "my-package.api.json",
+     *   },
+     * })
+     * ```
+     */
+    apiModel?: ApiModelOptions | boolean;
+}
+
+/**
+ * Transforms package.json for build output and publishing.
+ *
+ * @remarks
+ * This class consolidates all package.json transformation logic including:
+ * - Path transformations (src/ -> dist/, .ts -> .js)
+ * - Export conditions generation (types, import, require)
+ * - Bin field transformations
+ * - PNPM catalog and workspace resolution
+ * - Field cleanup for publishing
+ *
+ * @example
+ * ```typescript
+ * const transformer = new PackageJsonTransformer({
+ *   processTSExports: true,
+ *   collapseIndex: true,
+ * });
+ *
+ * // For production builds (resolves catalog: and workspace: references)
+ * const prodPkg = await transformer.transform(packageJson, { isProduction: true });
+ *
+ * // For development builds (preserves workspace links)
+ * const devPkg = await transformer.transform(packageJson, { isProduction: false });
+ * ```
+ *
+ * @public
+ */
+export declare class PackageJsonTransformer {
+    private readonly options;
+    private readonly pnpmCatalog;
+    constructor(options?: PackageJsonTransformOptions);
+    /**
+     * Transforms a single export path for RSLib compatibility.
+     *
+     * @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
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * transformer.createTypePath("./index.js");      // "./index.d.ts"
+     * transformer.createTypePath("./rslib/index.js"); // "./rslib.d.ts" (bundled)
+     * ```
+     */
+    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;
+    /**
+     * Transforms the bin field for build output.
+     *
+     * @param bin - The bin field from package.json
+     * @returns The transformed bin field
+     */
+    transformBin(bin: PackageJson["bin"]): PackageJson["bin"];
+    /**
+     * Performs the complete package.json transformation.
+     *
+     * @param packageJson - The source package.json
+     * @param context - Transform context
+     * @param context.isProduction - Whether this is a production build
+     * @param context.customTransform - Optional custom transform function
+     * @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
+     */
+    processTSExports?: boolean;
+    /**
+     * Whether to collapse index files (./foo/index.ts -> ./foo.js).
+     * This is typically true for bundled builds.
+     * @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.
+     *
+     * @remarks
+     * Useful in testing scenarios to ensure clean state between tests.
+     */
+    clearCache(): void;
+    /**
+     * Gets the PNPM catalog from pnpm-workspace.yaml.
+     *
+     * @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.
+     *
+     * @returns The catalog mapping dependency names to versions
+     */
+    getCatalog(): Promise<Record<string, string>>;
+    /**
+     * Resolves catalog: and workspace: references in a package.json.
+     *
+     * @param packageJson - The package.json to resolve
+     * @param dir - The directory containing the package (defaults to cwd)
+     * @returns The resolved package.json
+     *
+     * @throws {Error} 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.
+     */
+    private validateNoUnresolvedReferences;
+}
+
+/**
+ * Async RSLib configuration function type.
+ * @public
+ */
+export declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
+
+/**
+ * Strips sourceMappingURL comment from declaration file content.
+ * This removes comments like: `//# source` + `MappingURL=index.d.ts.map`
+ *
+ * @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.
+ *
+ * @public
+ */
+export declare function stripSourceMapComment(content: string): string;
+
+/**
+ * @public
+ */
+export declare type TransformPackageJsonFn = (context: {
+    target: BuildTarget;
+    pkg: PackageJson;
+}) => PackageJson;
+
+export { }