@savvy-web/rslib-builder 0.9.0 → 0.11.0

package/README.md

@@ -8,122 +8,45 @@ Build modern ESM Node.js libraries with minimal configuration. Handles
 TypeScript declarations, package.json transformations, and PNPM workspace
 resolution automatically.
 
-Building TypeScript packages for npm involves repetitive setup: configuring
-bundlers, generating declarations, transforming package.json exports, and
-resolving workspace references. rslib-builder handles these tasks so you can
-focus on your code.
-
 ## Features
 
-- **Zero Config** - Auto-detects entry points from package.json exports
-- **Fast Type Generation** - Uses tsgo (native TypeScript) for 10-100x faster
-  declaration generation
-- **Bundled Declarations** - Rolls up TypeScript types via API Extractor for
-  cleaner public APIs, with multi-entry support for packages with multiple exports
-- **Multi-Target Builds** - Separate dev (source maps) and npm (optimized)
-  outputs
-- **PNPM Integration** - Automatically resolves `catalog:` and `workspace:`
-  references
-- **Package.json Transform** - Converts `.ts` exports to `.js`, generates files
-  array, removes dev-only fields
-- **TSDoc Validation** - Pre-build TSDoc validation with automatic public API discovery
-- **API Model Generation** - Optional API model and resolved tsconfig output for
-  documentation tooling
-- **Extensible** - Add custom RSlib/Rsbuild plugins for advanced use cases
-
-## Prerequisites
-
-- Node.js 24.x or later
-- pnpm 10.x or later
-- TypeScript 5.9.x or later
+- **Zero-Config Entry Detection** - Auto-discovers entry points from package.json
+  exports, no manual configuration needed
+- **10-100x Faster Types** - Uses tsgo (native TypeScript compiler) with API
+  Extractor for bundled, clean public API declarations
+- **Production-Ready Transforms** - Converts `.ts` exports to `.js`, resolves
+  PNPM `catalog:` and `workspace:` references, generates files array
+- **Multi-Target Builds** - Separate dev (with source maps) and npm (optimized)
+  outputs from a single configuration
+- **TSDoc Validation** - Pre-build documentation validation with automatic
+  public API discovery
 
 ## Installation
 
 ```bash
-pnpm add -D @savvy-web/rslib-builder
-```
-
-### Peer Dependencies
-
-Install the required peer dependencies:
-
-```bash
-pnpm add -D @rslib/core @microsoft/api-extractor @typescript/native-preview
+npm install --save-dev @savvy-web/rslib-builder @rslib/core @microsoft/api-extractor @typescript/native-preview
 ```
 
 ## Quick Start
 
-Extend the provided tsconfig for optimal settings:
-
-```jsonc
-// tsconfig.json
-{
-  "extends": "@savvy-web/rslib-builder/tsconfig/ecma/lib.json"
-}
-```
-
-Create an `rslib.config.ts` in your project root:
-
 ```typescript
+// rslib.config.ts
 import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
 
 export default NodeLibraryBuilder.create({
   externals: ['@rslib/core'],
-  transform({ pkg, target }) {
-    if (target === 'npm') {
-      delete pkg.devDependencies;
-    }
-    return pkg;
-  },
 });
 ```
 
-Add scripts to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "build": "rslib build --env-mode dev",
-    "build:npm": "rslib build --env-mode npm"
-  }
-}
-```
+Build with `rslib build --env-mode dev` or `rslib build --env-mode npm`.
 
 ## Documentation
 
-For detailed documentation, see the [docs/](./docs/) directory:
-
-- [Getting Started](./docs/guides/getting-started.md) - Installation and setup
-- [Configuration](./docs/guides/configuration.md) - All options explained
-- [Plugin System](./docs/guides/plugins.md) - Built-in and custom plugins
-- [Architecture](./docs/architecture/overview.md) - How it works internally
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
-
-## Example
-
-This package builds itself using its own `NodeLibraryBuilder`. See
-[`rslib.config.ts`](./rslib.config.ts) for a production example.
-
-## Support
-
-This software is provided as-is under the MIT License with no warranty or
-support guarantees. While we welcome bug reports and feature requests via
-GitHub Issues, we cannot guarantee response times or resolution.
-
-For security vulnerabilities, please see [SECURITY.md](./SECURITY.md).
-
-## Links
-
-- [RSlib Documentation](https://rslib.dev/)
-- [Rsbuild Plugin API](https://rsbuild.dev/plugins/dev/core)
-- [API Extractor](https://api-extractor.com/)
-- [PNPM Workspace](https://pnpm.io/workspaces)
-- [PNPM Catalogs](https://pnpm.io/catalogs)
+For configuration options, API reference, and advanced usage, see [docs](./docs/).
 
 ## Contributing
 
-Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup
-and guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 

package/index.d.ts

@@ -395,6 +395,13 @@ export declare interface DtsPluginOptions {
      * Used to generate the correct temp tsconfig when tsconfigPath is not provided.
      */
     buildTarget?: "dev" | "npm";
+    /**
+     * Output format for the library.
+     * Affects the resolved tsconfig.json module settings:
+     * - `"esm"`: Uses ESNext module and Bundler resolution (default)
+     * - `"cjs"`: Uses CommonJS module and Node10 resolution
+     */
+    format?: "esm" | "cjs";
     /**
      * Options for API model generation.
      * When enabled, generates an `<unscopedPackageName>.api.json` file in the dist directory.
@@ -1055,6 +1062,17 @@ export declare type JsonPrimitive = string | number | boolean | null;
  */
 export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 
+/**
+ * Output format for library builds.
+ *
+ * @remarks
+ * - `"esm"` - ES Modules format (sets `type: "module"` in package.json)
+ * - `"cjs"` - CommonJS format (sets `type: "commonjs"` in package.json)
+ *
+ * @public
+ */
+export declare type LibraryFormat = "esm" | "cjs";
+
 /**
  * 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.
@@ -1137,6 +1155,7 @@ export declare class NodeLibraryBuilder {
      * Arrays are deep-copied to prevent mutation of this object.
      */
     static readonly DEFAULT_OPTIONS: {
+        format: "esm";
         plugins: never[];
         define: {};
         copyPatterns: never[];
@@ -1179,12 +1198,86 @@ export declare class NodeLibraryBuilder {
      * @returns Promise resolving to the RSLib configuration
      */
     static createSingleTarget(target: BuildTarget, opts: NodeLibraryBuilderOptions): Promise<RslibConfig>;
+    /**
+     * Checks if the current package has exports defined in package.json.
+     * @internal
+     */
+    private static packageHasExports;
 }
 
 /**
+ * Configuration options for the NodeLibraryBuilder.
+ *
+ * @remarks
+ * All options are optional with sensible defaults. The most commonly customized options are:
+ * - `externals`: For dependencies that should remain external
+ * - `dtsBundledPackages`: For inlining type definitions
+ * - `transform`: For custom package.json modifications
+ *
+ * @example
+ * ```typescript
+ * import type { NodeLibraryBuilderOptions } from '@savvy-web/rslib-builder';
+ *
+ * const options: NodeLibraryBuilderOptions = {
+ *   externals: ['@rslib/core'],
+ *   dtsBundledPackages: ['picocolors'],
+ *   apiModel: {
+ *     localPaths: ['../docs/packages/my-package'],
+ *   },
+ * };
+ * ```
+ *
  * @public
  */
 export declare interface NodeLibraryBuilderOptions {
+    /**
+     * Output format for main entry points.
+     * Also determines package.json `type` field:
+     * - `"esm"` → `"type": "module"`
+     * - `"cjs"` → `"type": "commonjs"`
+     *
+     * @defaultValue `"esm"`
+     */
+    format?: LibraryFormat;
+    /**
+     * Additional entry points bundled with custom output names.
+     * These entries bypass type generation and package.json exports
+     * but are included in the published package.
+     *
+     * @remarks
+     * Virtual entries are useful for special files like pnpm config files
+     * that need to be bundled but don't require type declarations or
+     * exposure as package exports.
+     *
+     * A module may have ONLY virtualEntries with no regular entry points.
+     *
+     * @example
+     * Mixed: regular entries + virtual entries
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   virtualEntries: {
+     *     "pnpmfile.cjs": {
+     *       source: "./src/pnpmfile.ts",
+     *       format: "cjs",
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     * Virtual-only: no regular entry points
+     * ```typescript
+     * NodeLibraryBuilder.create({
+     *   format: "cjs",
+     *   virtualEntries: {
+     *     "pnpmfile.cjs": {
+     *       source: "./src/pnpmfile.ts",
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    virtualEntries?: Record<string, VirtualEntryConfig>;
     /** Override entry points (optional - will auto-detect from package.json) */
     entry?: Record<string, string | string[]>;
     /**
@@ -1215,11 +1308,46 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     exportsAsIndexes?: boolean;
+    /**
+     * Patterns for files to copy to the output directory.
+     *
+     * @remarks
+     * Supports both string paths and detailed configuration objects.
+     * A `public/` directory in the project root is automatically added if it exists.
+     *
+     * @defaultValue `[]`
+     */
     copyPatterns: (string | CopyPatternConfig)[];
-    /** Additional plugins */
+    /**
+     * Additional Rsbuild plugins to include in the build.
+     *
+     * @remarks
+     * These plugins run after the built-in plugins (AutoEntryPlugin, DtsPlugin, etc.).
+     *
+     * @defaultValue `[]`
+     */
     plugins: RsbuildPlugin[];
+    /**
+     * Compile-time constants for code replacement.
+     *
+     * @remarks
+     * Values are stringified and replaced in the source code during bundling.
+     * The `process.env.__PACKAGE_VERSION__` constant is automatically defined.
+     *
+     * @see {@link https://rsbuild.dev/config/source/define | Rsbuild define documentation}
+     *
+     * @defaultValue `{}`
+     */
     define: SourceConfig["define"];
-    /** Path to tsconfig for build (default: ./tsconfig.build.json) */
+    /**
+     * Path to the TypeScript configuration file for the build.
+     *
+     * @remarks
+     * If not specified, the plugin searches for `tsconfig.json` in the project root.
+     * A temporary tsconfig is generated for declaration generation regardless of this setting.
+     *
+     * @defaultValue `undefined` (auto-detected)
+     */
     tsconfigPath: string | undefined;
     /** Build targets to include (default: ["dev", "npm"]) */
     targets?: BuildTarget[];
@@ -1800,7 +1928,6 @@ export declare type PackageJson = JsonObject & PackageJson.NodeJsStandard & Pack
  *
  * - 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
@@ -1848,6 +1975,15 @@ export declare const PackageJsonTransformPlugin: (options?: PackageJsonTransform
  * @public
  */
 export declare interface PackageJsonTransformPluginOptions {
+    /**
+     * Output format for the library.
+     * Determines the package.json `type` field:
+     * - `"esm"` → `"type": "module"`
+     * - `"cjs"` → `"type": "commonjs"`
+     *
+     * @defaultValue `"esm"`
+     */
+    format?: LibraryFormat;
     /**
      * Override the package name in the output package.json.
      *
@@ -2332,8 +2468,14 @@ export declare class TsconfigResolver {
      * - Excludes file selection (include, exclude, files, references)
      * - Adds $schema for IDE support
      *
+     * When `format` is `"cjs"`, the resolved config uses CommonJS-compatible settings:
+     * - `module: "commonjs"`
+     * - `moduleResolution: "node10"`
+     * - `esModuleInterop: true`
+     *
      * @param parsed - The parsed TypeScript configuration from `parseJsonConfigFileContent`
      * @param _rootDir - Reserved for future path normalization (currently unused)
+     * @param format - Optional output format to adjust module settings (`"esm"` or `"cjs"`)
      * @returns A JSON-serializable tsconfig object
      * @throws {@link TsconfigResolverError} If resolution fails for any option
          *
@@ -2353,7 +2495,7 @@ export declare class TsconfigResolver {
          *
          * @public
          */
-     resolve(parsed: ParsedCommandLine, _rootDir: string): ResolvedTsconfig;
+     resolve(parsed: ParsedCommandLine, _rootDir: string, format?: LibraryFormat): ResolvedTsconfig;
      /**
       * Adds converted enum options to the compiler options object.
       * @internal
@@ -2933,4 +3075,82 @@ export declare class TsconfigResolver {
      */
     export declare type TsDocTagGroup = "core" | "extended" | "discretionary";
 
+    /**
+     * Configuration for a virtual entry point.
+     *
+     * @remarks
+     * Virtual entries are bundled entry points that bypass type generation
+     * and package.json exports while still being included in the published package.
+     *
+     * @example
+     * ```typescript
+     * const config: VirtualEntryConfig = {
+     *   source: "./src/pnpmfile.ts",
+     *   format: "cjs",
+     * };
+     * ```
+     *
+     * @public
+     */
+    export declare interface VirtualEntryConfig {
+        /**
+         * Path to source file (relative to package root).
+         */
+        source: string;
+        /**
+         * Output format for this entry.
+         * If not specified, inherits from top-level `format` option.
+         */
+        format?: LibraryFormat;
+    }
+
+    /**
+     * Plugin to handle virtual entry points in RSlib builds.
+     *
+     * @remarks
+     * Virtual entries are special entry points that:
+     * - Are bundled like regular entries
+     * - Do NOT generate TypeScript declarations (.d.ts files)
+     * - Are NOT added to package.json exports
+     * - ARE added to package.json files array for publishing
+     *
+     * This plugin:
+     * 1. Exposes the virtual entry names for DtsPlugin to skip type generation
+     * 2. Adds virtual entry outputs to the files array in the additional stage
+     *
+     * @example
+     * ```typescript
+     * import { VirtualEntryPlugin } from '@savvy-web/rslib-builder';
+     *
+     * const plugin = VirtualEntryPlugin({
+     *   virtualEntryNames: new Set(['pnpmfile']),
+     * });
+     * ```
+     *
+     * @public
+     */
+    export declare const VirtualEntryPlugin: (options: VirtualEntryPluginOptions) => RsbuildPlugin;
+
+    /**
+     * Options for the VirtualEntryPlugin.
+     *
+     * @remarks
+     * Virtual entries are used for special files that need bundling but should not
+     * generate type declarations or appear in package.json exports. Common use cases
+     * include pnpmfile.cjs or other configuration files.
+     *
+     * @public
+     */
+    export declare interface VirtualEntryPluginOptions {
+        /**
+         * Set of virtual entry names (without file extensions).
+         *
+         * @remarks
+         * These names are exposed to DtsPlugin to skip type generation.
+         * For example, if `virtualEntryNames` contains `"pnpmfile"`, the
+         * entry `pnpmfile.cjs` will be bundled but no `pnpmfile.d.ts` will be generated.
+         */
+        virtualEntryNames: Set<string>;
+    }
+
     export { }

package/index.js

@@ -1,11 +1,11 @@
 /*! For license information please see index.js.LICENSE.txt */
-import { constants, existsSync, writeFileSync } from "node:fs";
+import { constants, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, relative, resolve as external_node_path_resolve } from "node:path";
 import { defineConfig } from "@rslib/core";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, unlink as promises_unlink, writeFile } from "node:fs/promises";
 import { logger as core_logger } from "@rsbuild/core";
 import picocolors from "picocolors";
-import { getWorkspaceRoot } from "workspace-tools";
+import { getCatalogs, getWorkspaceManagerAndRoot, getWorkspaceManagerRoot } from "workspace-tools";
 import { spawn } from "node:child_process";
 import { StandardTags, Standardization, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
 import deep_equal from "deep-equal";
@@ -13,8 +13,11 @@ import typescript, { ImportsNotUsedAsValues, JsxEmit, ModuleDetectionKind, Modul
 import { createRequire } from "node:module";
 import { inspect } from "node:util";
 import sort_package_json from "sort-package-json";
+import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";
+import { parseCatalogProtocol } from "@pnpm/catalogs.protocol-parser";
 import { createExportableManifest } from "@pnpm/exportable-manifest";
-import { parse } from "yaml";
+import { readWantedLockfile } from "@pnpm/lockfile.fs";
+import { readWorkspaceManifest } from "@pnpm/workspace.read-manifest";
 const { cyan: cyan, dim: dim, bold: bold } = picocolors;
 function formatTime(ms) {
     if (ms < 1000) return `${ms}ms`;
@@ -169,7 +172,7 @@ function getApiExtractorPath() {
     const cwd = process.cwd();
     const localApiExtractor = join(cwd, "node_modules", "@microsoft", "api-extractor");
     if (existsSync(localApiExtractor)) return localApiExtractor;
-    const workspaceRoot = getWorkspaceRoot(cwd);
+    const workspaceRoot = getWorkspaceManagerRoot(cwd);
     if (workspaceRoot) {
         const workspaceApiExtractor = join(workspaceRoot, "node_modules", "@microsoft", "api-extractor");
         if (existsSync(workspaceApiExtractor)) return workspaceApiExtractor;
@@ -310,21 +313,6 @@ class TSConfigFile {
     }
 }
 class LibraryTSConfigFile extends TSConfigFile {
-    bundle(target) {
-        const config = transformStringsDeep(this.config, (str)=>str.replace("${configDir}", "../../../../../.."));
-        const include = config.include?.filter((pattern)=>pattern.includes("/src/") || pattern.includes("/types/") || pattern.includes("/public/") || pattern.includes("package.json")).filter((pattern)=>!pattern.includes(".tsx") && !pattern.includes(".cts"));
-        return {
-            ...config,
-            compilerOptions: {
-                ...config.compilerOptions,
-                outDir: "dist",
-                tsBuildInfoFile: `${process.cwd()}/dist/.tsbuildinfo.${target}.bundle`
-            },
-            ...void 0 !== include && include.length > 0 ? {
-                include
-            } : {}
-        };
-    }
     writeBundleTempConfig(_target) {
         const cwd = process.cwd();
         const baseConfig = this.config;
@@ -679,7 +667,7 @@ class TsconfigResolver {
         const filename = lib.includes("/") || lib.includes("\\") ? lib.split(/[\\/]/).pop() ?? lib : lib;
         return filename.replace(/^lib\./, "").replace(/\.d\.ts$/, "");
     }
-    resolve(parsed, _rootDir) {
+    resolve(parsed, _rootDir, format) {
         const opts = parsed.options;
         const compilerOptions = {};
         this.addEnumOptions(compilerOptions, opts);
@@ -688,6 +676,11 @@ class TsconfigResolver {
         compilerOptions.noEmit = true;
         this.addPreservedBooleanOptions(compilerOptions, opts);
         this.addPreservedStringOptions(compilerOptions, opts);
+        if ("cjs" === format) {
+            compilerOptions.module = "commonjs";
+            compilerOptions.moduleResolution = "node10";
+            compilerOptions.esModuleInterop = true;
+        }
         return {
             $schema: TSCONFIG_SCHEMA_URL,
             compilerOptions
@@ -836,7 +829,7 @@ function getTsgoBinPath() {
     const cwd = process.cwd();
     const localTsgoBin = join(cwd, "node_modules", ".bin", "tsgo");
     if (existsSync(localTsgoBin)) return localTsgoBin;
-    const workspaceRoot = getWorkspaceRoot(cwd);
+    const workspaceRoot = getWorkspaceManagerRoot(cwd);
     if (workspaceRoot) {
         const workspaceTsgoBin = join(workspaceRoot, "node_modules", ".bin", "tsgo");
         if (existsSync(workspaceTsgoBin)) return workspaceTsgoBin;
@@ -1240,8 +1233,13 @@ function runTsgo(options) {
                         const extractor = new EntryExtractor();
                         const { entries } = extractor.extract(packageJson);
                         const entryPoints = new Map();
+                        const virtualEntryNames = api.useExposed("virtual-entry-names");
                         for (const [entryName, sourcePath] of Object.entries(entries)){
                             if (entryName.startsWith("bin/")) continue;
+                            if (virtualEntryNames?.has(entryName)) {
+                                log.global.info(`Skipping type generation for virtual entry: ${entryName}`);
+                                continue;
+                            }
                             if (!sourcePath.match(/\.(ts|mts|cts|tsx)$/)) continue;
                             if (sourcePath.includes(".test.") || sourcePath.includes("__test__")) continue;
                             const resolvedSourcePath = sourcePath.startsWith(".") ? join(cwd, sourcePath) : sourcePath;
@@ -1332,7 +1330,7 @@ function runTsgo(options) {
                             }
                             if (apiModelPath && state.parsedConfig && state.tsconfigPath) {
                                 const resolver = new TsconfigResolver();
-                                const resolvedTsconfig = resolver.resolve(state.parsedConfig, cwd);
+                                const resolvedTsconfig = resolver.resolve(state.parsedConfig, cwd, options.format);
                                 const tsconfigContent = `${JSON.stringify(resolvedTsconfig, null, "\t")}\n`;
                                 const tsconfigSource = new context.sources.OriginalSource(tsconfigContent, "tsconfig.json");
                                 context.compilation.emitAsset("tsconfig.json", tsconfigSource);
@@ -1566,75 +1564,76 @@ const FilesArrayPlugin = (options)=>({
     });
 const CATALOG_PREFIX = "catalog:";
 const WORKSPACE_PREFIX = "workspace:";
-class PnpmCatalog {
-    catalogCache = null;
-    catalogCacheMtime = null;
-    cachedWorkspaceRoot = null;
+class WorkspaceCatalog {
+    catalogsCache = null;
+    cachedWorkspaceInfo = null;
     clearCache() {
-        this.catalogCache = null;
-        this.catalogCacheMtime = null;
-        this.cachedWorkspaceRoot = null;
+        this.catalogsCache = null;
+        this.cachedWorkspaceInfo = null;
     }
-    async getCatalog() {
-        try {
-            if (!this.cachedWorkspaceRoot) {
-                this.cachedWorkspaceRoot = getWorkspaceRoot(process.cwd());
-                if (!this.cachedWorkspaceRoot) throw new Error("Could not find workspace root - ensure you're in a workspace");
-            }
-            const workspaceFile = external_node_path_resolve(this.cachedWorkspaceRoot, "pnpm-workspace.yaml");
-            const stats = await stat(workspaceFile);
-            const currentMtime = stats.mtime.getTime();
-            if (null !== this.catalogCache && this.catalogCacheMtime === currentMtime) return this.catalogCache;
-            const content = await readFile(workspaceFile, "utf-8");
-            const workspace = parse(content);
-            this.catalogCache = workspace.catalog ?? {};
-            this.catalogCacheMtime = currentMtime;
-            return this.catalogCache;
-        } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+    async getCatalogs() {
+        if (null !== this.catalogsCache) return this.catalogsCache;
+        const workspaceInfo = this.getWorkspaceInfo();
+        if (!workspaceInfo) {
             const logger = createEnvLogger("catalog");
-            if (errorMessage.includes("ENOENT") && errorMessage.includes("pnpm-workspace.yaml")) {
-                logger.error("Failed to read pnpm catalog: workspace configuration not found");
-                logger.error("  -> Ensure you're in a pnpm workspace with proper configuration");
-            } else if (errorMessage.includes("YAML")) {
-                logger.error("Failed to read pnpm catalog: Invalid YAML syntax in workspace configuration");
-                logger.error("  -> Check workspace configuration file syntax");
-            } else logger.error(`Failed to read pnpm catalog from pnpm-workspace.yaml: ${errorMessage}`);
+            logger.error("Could not find workspace root - ensure you're in a workspace");
             return {};
         }
+        const { manager, root } = workspaceInfo;
+        if ("pnpm" === manager) this.catalogsCache = await this.readPnpmCatalogs(root);
+        else if ("yarn" === manager) this.catalogsCache = this.readYarnCatalogs(root);
+        else this.catalogsCache = {};
+        return this.catalogsCache;
     }
     async resolvePackageJson(packageJson, dir = process.cwd()) {
-        const logger = createEnvLogger("pnpm");
+        const workspaceInfo = this.getWorkspaceInfo();
+        const loggerName = workspaceInfo?.manager === "yarn" ? "yarn" : "pnpm";
+        const logger = createEnvLogger(loggerName);
         try {
-            const catalog = await this.getCatalog();
-            const catalogDeps = this.collectDependencies(packageJson, CATALOG_PREFIX);
+            const catalogs = await this.getCatalogs();
+            const catalogDeps = this.collectCatalogDependencies(packageJson);
             const workspaceDeps = this.collectDependencies(packageJson, WORKSPACE_PREFIX);
             const hasCatalogDeps = catalogDeps.length > 0;
             const hasWorkspaceDeps = workspaceDeps.length > 0;
-            if (hasCatalogDeps && 0 === Object.keys(catalog).length) {
-                const error = `Package contains ${CATALOG_PREFIX} dependencies but catalog configuration is missing`;
-                logger.error(error);
-                logger.error("  -> Catalog dependencies found:");
-                for (const { field, dependency, version } of catalogDeps)logger.error(`    - ${field}.${dependency}: ${version}`);
-                throw new Error(error);
+            if (hasCatalogDeps) {
+                const missingCatalogs = this.findMissingCatalogs(catalogDeps, catalogs);
+                if (missingCatalogs.size > 0) {
+                    const available = Object.keys(catalogs).join(", ") || "none";
+                    const error = `Catalog(s) not found: ${[
+                        ...missingCatalogs
+                    ].join(", ")}. Available: ${available}`;
+                    logger.error(error);
+                    logger.error("  -> Catalog dependencies found:");
+                    for (const { field, dependency, version, catalogName } of catalogDeps)if (missingCatalogs.has(catalogName)) logger.error(`    - ${field}.${dependency}: ${version}`);
+                    throw new Error(error);
+                }
+                logger.info(`Resolving ${catalogDeps.length} ${CATALOG_PREFIX} dependencies`);
             }
-            if (hasCatalogDeps) logger.info(`Resolving ${catalogDeps.length} ${CATALOG_PREFIX} dependencies`);
             if (hasWorkspaceDeps) logger.info(`Resolving ${workspaceDeps.length} ${WORKSPACE_PREFIX} dependencies`);
             const result = await createExportableManifest(dir, packageJson, {
-                catalogs: {
-                    default: catalog
-                }
+                catalogs
             });
-            if (hasCatalogDeps || hasWorkspaceDeps) this.logResolvedDependencies(result, [
-                ...catalogDeps,
-                ...workspaceDeps
-            ], logger);
+            if (hasCatalogDeps || hasWorkspaceDeps) {
+                const allDeps = [
+                    ...catalogDeps.map((d)=>({
+                            field: d.field,
+                            dependency: d.dependency,
+                            source: "default" === d.catalogName ? "catalog:" : `catalog:${d.catalogName}`
+                        })),
+                    ...workspaceDeps.map((d)=>({
+                            field: d.field,
+                            dependency: d.dependency,
+                            source: "workspace:"
+                        }))
+                ];
+                this.logResolvedDependencies(result, allDeps, logger);
+            }
             this.validateNoUnresolvedReferences(result, logger);
             return result;
         } catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            if (errorMessage.startsWith("Transformation failed:") || errorMessage.includes(`Package contains ${CATALOG_PREFIX} dependencies`)) throw error;
-            logger.error(`Failed to apply pnpm transformations for directory ${dir}: ${errorMessage}`);
+            if (errorMessage.startsWith("Transformation failed:") || errorMessage.startsWith("Catalog(s) not found:")) throw error;
+            logger.error(`Failed to apply transformations for directory ${dir}: ${errorMessage}`);
             if (errorMessage.includes("catalog")) {
                 logger.error(`  -> Catalog resolution failed - check workspace configuration and ${CATALOG_PREFIX} dependencies`);
                 throw new Error("Catalog resolution failed");
@@ -1648,9 +1647,90 @@ class PnpmCatalog {
                 throw new Error(`Manifest processing failed: ${errorMessage}`);
             }
             logger.error("  -> Cannot proceed with invalid package.json transformations");
-            throw new Error(`PNPM transformation failed: ${errorMessage}`);
+            throw new Error(`Transformation failed: ${errorMessage}`);
         }
     }
+    getWorkspaceInfo() {
+        if (null !== this.cachedWorkspaceInfo) return this.cachedWorkspaceInfo;
+        const info = getWorkspaceManagerAndRoot(process.cwd());
+        this.cachedWorkspaceInfo = info ?? null;
+        return this.cachedWorkspaceInfo;
+    }
+    async readPnpmCatalogs(workspaceRoot) {
+        const lockfileCatalogs = await this.readPnpmLockfileCatalogs(workspaceRoot);
+        if (Object.keys(lockfileCatalogs).length > 0) return lockfileCatalogs;
+        return this.readPnpmWorkspaceCatalogs(workspaceRoot);
+    }
+    async readPnpmLockfileCatalogs(workspaceRoot) {
+        try {
+            const lockfile = await readWantedLockfile(workspaceRoot, {
+                ignoreIncompatible: true
+            });
+            if (!lockfile?.catalogs) return {};
+            return this.convertLockfileCatalogs(lockfile.catalogs);
+        } catch  {
+            return {};
+        }
+    }
+    async readPnpmWorkspaceCatalogs(workspaceRoot) {
+        try {
+            const manifest = await readWorkspaceManifest(workspaceRoot);
+            return getCatalogsFromWorkspaceManifest(manifest);
+        } catch  {
+            return {};
+        }
+    }
+    readYarnCatalogs(workspaceRoot) {
+        const catalogs = getCatalogs(workspaceRoot, "yarn");
+        if (!catalogs) return {};
+        return this.convertWorkspaceToolsCatalogs(catalogs);
+    }
+    convertLockfileCatalogs(snapshots) {
+        const result = {};
+        for (const [name, entries] of Object.entries(snapshots)){
+            result[name] = {};
+            for (const [dep, entry] of Object.entries(entries))result[name][dep] = entry.specifier;
+        }
+        return result;
+    }
+    convertWorkspaceToolsCatalogs(catalogs) {
+        const result = {};
+        if (catalogs.default) result.default = {
+            ...catalogs.default
+        };
+        if (catalogs.named) for (const [name, catalog] of Object.entries(catalogs.named))result[name] = {
+            ...catalog
+        };
+        return result;
+    }
+    collectCatalogDependencies(packageJson) {
+        const deps = [];
+        const fields = [
+            "dependencies",
+            "devDependencies",
+            "peerDependencies",
+            "optionalDependencies"
+        ];
+        for (const field of fields){
+            const fieldDeps = packageJson[field];
+            if (fieldDeps) for (const [dependency, version] of Object.entries(fieldDeps)){
+                if ("string" != typeof version || !version.startsWith(CATALOG_PREFIX)) continue;
+                const catalogName = parseCatalogProtocol(version);
+                if (catalogName) deps.push({
+                    field,
+                    dependency,
+                    version,
+                    catalogName
+                });
+            }
+        }
+        return deps;
+    }
+    findMissingCatalogs(deps, catalogs) {
+        const missing = new Set();
+        for (const { catalogName } of deps)if (!catalogs[catalogName]) missing.add(catalogName);
+        return missing;
+    }
     collectDependencies(packageJson, prefix) {
         const deps = [];
         const fields = [
@@ -1673,28 +1753,35 @@ class PnpmCatalog {
     }
     logResolvedDependencies(resultPkg, originalDeps, logger) {
         const allResolved = {};
-        for (const { field, dependency } of originalDeps){
+        for (const { field, dependency, source } of originalDeps){
             const deps = resultPkg[field];
             if (deps?.[dependency]) {
                 if (!allResolved[field]) allResolved[field] = [];
                 allResolved[field].push({
                     dependency,
-                    version: deps[dependency]
+                    version: deps[dependency],
+                    source
                 });
             }
         }
         if (Object.keys(allResolved).length > 0) {
-            logger.info("Resolved dependencies:");
+            logger.global.info("Resolved dependencies:");
             for (const [field, deps] of Object.entries(allResolved)){
-                logger.info(`- ${field}:`);
-                for (const { dependency, version } of deps)logger.info(`    ${dependency}: ${version}`);
+                logger.global.info(`- ${field}:`);
+                for (const { dependency, version, source } of deps)logger.global.info(`    ${dependency}: ${version} (${source})`);
             }
         }
     }
     validateNoUnresolvedReferences(resultPkg, logger) {
+        const unresolvedCatalog = this.collectCatalogDependencies(resultPkg);
+        const unresolvedWorkspace = this.collectDependencies(resultPkg, WORKSPACE_PREFIX);
         const unresolvedDeps = [
-            ...this.collectDependencies(resultPkg, CATALOG_PREFIX),
-            ...this.collectDependencies(resultPkg, WORKSPACE_PREFIX)
+            ...unresolvedCatalog.map((d)=>({
+                    field: d.field,
+                    dependency: d.dependency,
+                    version: d.version
+                })),
+            ...unresolvedWorkspace
         ];
         if (unresolvedDeps.length > 0) {
             const catalogRefs = unresolvedDeps.filter((dep)=>dep.version.startsWith(CATALOG_PREFIX));
@@ -1711,10 +1798,8 @@ class PnpmCatalog {
         }
     }
 }
-let defaultInstance = null;
-function getDefaultPnpmCatalog() {
-    if (!defaultInstance) defaultInstance = new PnpmCatalog();
-    return defaultInstance;
+function createWorkspaceCatalog() {
+    return new WorkspaceCatalog();
 }
 function transformExportPath(path, processTSExports = true, collapseIndex = false) {
     let transformedPath = path;
@@ -1819,8 +1904,9 @@ function applyRslibTransformations(packageJson, originalPackageJson, processTSEx
     });
     return sort_package_json(processedManifest);
 }
-async function applyPnpmTransformations(packageJson, dir = process.cwd()) {
-    return getDefaultPnpmCatalog().resolvePackageJson(packageJson, dir);
+async function applyPnpmTransformations(packageJson, dir = process.cwd(), catalog) {
+    const workspaceCatalog = catalog ?? createWorkspaceCatalog();
+    return workspaceCatalog.resolvePackageJson(packageJson, dir);
 }
 async function buildPackageJson(packageJson, isProduction = false, processTSExports = true, entrypoints, exportToOutputMap, bundle, transform) {
     let result;
@@ -1831,12 +1917,9 @@ async function buildPackageJson(packageJson, isProduction = false, processTSExpo
     if (transform) result = transform(result);
     return result;
 }
-const PackageJsonTransformPlugin = (options = {})=>{
-    const cache = new Map();
-    return {
+const PackageJsonTransformPlugin = (options = {})=>({
         name: "package-json-processor",
         setup (api) {
-            api.expose("files-cache", cache);
             let filesArray = api.useExposed("files-array");
             if (!filesArray) {
                 filesArray = new Set();
@@ -1864,6 +1947,7 @@ const PackageJsonTransformPlugin = (options = {})=>{
                 const processedPackageJson = await buildPackageJson(packageJson.data, isProduction, options.processTSExports, entrypoints, exportToOutputMap, options.bundle, options.transform);
                 packageJson.data = processedPackageJson;
                 if (options.forcePrivate) packageJson.data.private = true;
+                if (options.format) packageJson.data.type = "esm" === options.format ? "module" : "commonjs";
                 const useRollupTypes = api.useExposed("use-rollup-types");
                 if (useRollupTypes && packageJson.data.exports && "object" == typeof packageJson.data.exports) {
                     const exports = packageJson.data.exports;
@@ -1884,8 +1968,7 @@ const PackageJsonTransformPlugin = (options = {})=>{
                 }
             });
         }
-    };
-};
+    });
 class ImportGraph {
     options;
     sys;
@@ -2302,12 +2385,35 @@ const TsDocLintPlugin = (options = {})=>{
         }
     };
 };
+const VirtualEntryPlugin = (options)=>{
+    const { virtualEntryNames } = options;
+    return {
+        name: "virtual-entry-plugin",
+        setup (api) {
+            api.expose("virtual-entry-names", virtualEntryNames);
+            api.processAssets({
+                stage: "additional"
+            }, async (context)=>{
+                let filesArray = api.useExposed("files-array");
+                if (!filesArray) {
+                    filesArray = new Set();
+                    api.expose("files-array", filesArray);
+                }
+                for (const assetName of Object.keys(context.compilation.assets)){
+                    const baseName = assetName.replace(/\.(c|m)?js$/, "");
+                    if (virtualEntryNames.has(baseName)) filesArray.add(assetName);
+                }
+            });
+        }
+    };
+};
 /* v8 ignore next -- @preserve */ class NodeLibraryBuilder {
     static VALID_TARGETS = [
         "dev",
         "npm"
     ];
     static DEFAULT_OPTIONS = {
+        format: "esm",
         plugins: [],
         define: {},
         copyPatterns: [],
@@ -2332,6 +2438,7 @@ const TsDocLintPlugin = (options = {})=>{
             plugins: options.plugins ?? NodeLibraryBuilder.DEFAULT_OPTIONS.plugins,
             define: options.define ?? NodeLibraryBuilder.DEFAULT_OPTIONS.define,
             tsconfigPath: options.tsconfigPath,
+            format: options.format ?? NodeLibraryBuilder.DEFAULT_OPTIONS.format,
             targets: options.targets ?? NodeLibraryBuilder.DEFAULT_OPTIONS.targets,
             externals: options.externals ?? NodeLibraryBuilder.DEFAULT_OPTIONS.externals,
             apiModel: options.apiModel ?? NodeLibraryBuilder.DEFAULT_OPTIONS.apiModel,
@@ -2349,6 +2456,9 @@ const TsDocLintPlugin = (options = {})=>{
             },
             ...void 0 !== options.transform && {
                 transform: options.transform
+            },
+            ...void 0 !== options.virtualEntries && {
+                virtualEntries: options.virtualEntries
             }
         };
         return merged;
@@ -2387,10 +2497,12 @@ const TsDocLintPlugin = (options = {})=>{
                 target,
                 pkg
             }) : void 0;
+        const libraryFormat = options.format ?? "esm";
         plugins.push(PackageJsonTransformPlugin({
             forcePrivate: "dev" === target,
             bundle: true,
             target,
+            format: libraryFormat,
             ...transformFn && {
                 transform: transformFn
             }
@@ -2415,6 +2527,7 @@ const TsDocLintPlugin = (options = {})=>{
                 bundledPackages: options.dtsBundledPackages
             },
             buildTarget: target,
+            format: libraryFormat,
             ...void 0 !== apiModelForTarget && {
                 apiModel: apiModelForTarget
             }
@@ -2437,9 +2550,9 @@ const TsDocLintPlugin = (options = {})=>{
                     externals: options.externals
                 }
             },
-            format: "esm",
+            format: libraryFormat,
             experiments: {
-                advancedEsm: true
+                advancedEsm: "esm" === libraryFormat
             },
             bundle: true,
             plugins,
@@ -2456,10 +2569,70 @@ const TsDocLintPlugin = (options = {})=>{
                 }
             }
         };
+        const hasRegularEntries = void 0 !== options.entry || NodeLibraryBuilder.packageHasExports();
+        const virtualEntries = options.virtualEntries ?? {};
+        const hasVirtualEntries = Object.keys(virtualEntries).length > 0;
+        if (!hasRegularEntries && !hasVirtualEntries) throw new Error("No entry points configured. Provide package.json exports, explicit entry option, or virtualEntries.");
+        const libConfigs = [];
+        if (hasRegularEntries) libConfigs.push(lib);
+        if (hasVirtualEntries) {
+            const virtualByFormat = new Map();
+            for (const [outputName, config] of Object.entries(virtualEntries)){
+                const entryFormat = config.format ?? libraryFormat;
+                if (!virtualByFormat.has(entryFormat)) virtualByFormat.set(entryFormat, new Map());
+                const entryName = outputName.replace(/\.(c|m)?js$/, "");
+                const formatMap = virtualByFormat.get(entryFormat);
+                if (formatMap) formatMap.set(entryName, config.source);
+            }
+            for (const [format, entries] of virtualByFormat){
+                const virtualEntryNames = new Set(entries.keys());
+                const entryMap = Object.fromEntries(entries);
+                const virtualLib = {
+                    id: `${target}-virtual-${format}`,
+                    format,
+                    bundle: true,
+                    output: {
+                        target: "node",
+                        cleanDistPath: false,
+                        sourceMap: false,
+                        distPath: {
+                            root: outputDir
+                        },
+                        ...options.externals && options.externals.length > 0 && {
+                            externals: options.externals
+                        }
+                    },
+                    source: {
+                        entry: entryMap
+                    },
+                    plugins: [
+                        VirtualEntryPlugin({
+                            virtualEntryNames
+                        }),
+                        FilesArrayPlugin({
+                            target
+                        })
+                    ]
+                };
+                libConfigs.push(virtualLib);
+            }
+            if (hasRegularEntries) {
+                const allVirtualEntryNames = new Set();
+                for (const outputName of Object.keys(virtualEntries)){
+                    const entryName = outputName.replace(/\.(c|m)?js$/, "");
+                    allVirtualEntryNames.add(entryName);
+                }
+                plugins.push({
+                    name: "virtual-entry-names-exposer",
+                    setup (api) {
+                        api.expose("virtual-entry-names", allVirtualEntryNames);
+                    }
+                });
+                lib.plugins = plugins;
+            }
+        }
         return defineConfig({
-            lib: [
-                lib
-            ],
+            lib: libConfigs,
             ...options.tsconfigPath && {
                 source: {
                     tsconfigPath: options.tsconfigPath
@@ -2472,5 +2645,15 @@ const TsDocLintPlugin = (options = {})=>{
             }
         });
     }
+    static packageHasExports() {
+        try {
+            const packageJsonPath = join(process.cwd(), "package.json");
+            const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+            const { exports } = packageJson;
+            return null != exports && "object" == typeof exports && Object.keys(exports).length > 0;
+        } catch  {
+            return false;
+        }
+    }
 }
-export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, extractEntriesFromPackageJson };
+export { AutoEntryPlugin, DtsPlugin, EntryExtractor, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder, TsDocLintPlugin, TsconfigResolver, TsconfigResolverError, VirtualEntryPlugin, extractEntriesFromPackageJson };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rslib-builder",
-	"version": "0.9.0",
+	"version": "0.11.0",
 	"private": false,
 	"description": "RSlib-based build system for Node.js libraries with automatic package.json transformation, TypeScript declaration bundling, and multi-target support",
 	"keywords": [
@@ -45,7 +45,11 @@
 	"dependencies": {
 		"@microsoft/tsdoc": "^0.16.0",
 		"@microsoft/tsdoc-config": "^0.18.0",
+		"@pnpm/catalogs.config": "^1000.0.5",
+		"@pnpm/catalogs.protocol-parser": "^1001.0.0",
 		"@pnpm/exportable-manifest": "^1000.3.1",
+		"@pnpm/lockfile.fs": "^1001.1.29",
+		"@pnpm/workspace.read-manifest": "^1000.2.10",
 		"@typescript-eslint/parser": "^8.53.1",
 		"deep-equal": "^2.2.3",
 		"eslint": "^9.39.2",
@@ -54,8 +58,7 @@
 		"picocolors": "^1.1.1",
 		"sort-package-json": "^3.6.1",
 		"tmp": "^0.2.5",
-		"workspace-tools": "^0.40.4",
-		"yaml": "^2.8.2"
+		"workspace-tools": "^0.41.0"
 	},
 	"peerDependencies": {
 		"@microsoft/api-extractor": "^7.55.2",